Skip to content

Home

Jump to bottom
Nima Naseri edited this page Dec 3, 2025 · 2 revisions

Welcome to the cortex wiki!

Table of Contents

Usage

Database Initialization

cortex init

Prompts:

  • Master password: [hidden - min 8 chars with complexity requirements]
  • Confirm password: [hidden]

Output: Initialized.

Security Notes:

  • Master password requirements enforced
  • Database and salt created in secure directory
  • Initial backup created automatically
  • File permissions set to 0700 (Unix)

Creating Password Entries

Basic creation:

cortex create "github-work"

With tags:

cortex create "github-work" --tags "work,dev,critical"

Prompts:

  • Master password: [hidden or cached session]
  • Password to store: [hidden - min 4 chars]
  • Confirm password: [hidden]
  • Description (optional): [max 500 chars]

Output: Created 'github-work'. and Tags: work, dev, critical

Validation:

  • Name cannot start with __ (reserved prefix)
  • Password minimum 4 characters
  • Description cannot contain password fragments
  • Description maximum 500 characters
  • Tags normalized (lowercase, sorted, deduplicated)

Retrieving Passwords

Display in terminal:

cortex get "github-work"

Copy to clipboard (default 43s):

cortex get "github-work" --clip

Copy to clipboard (custom timeout):

cortex get "github-work" --clip 120

Output:

github-work: your_secure_password_123
Description: Work GitHub account for project X

Clipboard mode output:

Password copied to clipboard for 120 seconds...
Description: Work GitHub account for project X
Done.

Clipboard Options:

  • Timeout range: 3-540 seconds
  • Default: 43 seconds
  • Auto-clear after timeout
  • Interrupt with Ctrl+C to clear immediately

Listing Entries

Basic list:

cortex list

With tags (deprecated flag, tags always shown):

cortex list --tags

Output:

Entry: github-work
Description: Work GitHub account for project X
Tags: work, dev, critical

Entry: aws-prod
Description: Production AWS credentials
Tags: cloud, production

Editing Entries

Edit password and description:

cortex edit "github-work"

Replace tags:

cortex edit "github-work" --tags "work,dev,updated"

Prompts:

  • Master password: [hidden or cached]
  • New password (Enter to keep current): [hidden]
  • Confirm new password: [if password changed]
  • New description (Enter to keep current): [text]

Output: Edited for 'github-work'. or No changes made to 'github-work'.

Behavior:

  • Empty inputs keep current values
  • Tags flag replaces all existing tags
  • No-op detected automatically

Deleting Entries

cortex delete "old-account"

Output: Deleted 'old-account'. or Account 'old-account' not found.

Restrictions: Cannot delete system entries (names starting with __)

Searching Entries

Basic search:

cortex find "github"

Advanced search:

cortex find "aws" --ignore-case --names-only

Output:

Found 2 match(es) for: github

Entry: github-work
  >> Matches: name and tags
  Description: Work GitHub account for project X
  Tags: work, dev, critical

Entry: github-personal
  >> Matches: description
  Description: Personal GitHub for side projects
  Tags: personal, dev

Options:

  • --ignore-case, -i: Case-insensitive matching
  • --names-only, -n: Search only entry names
  • Supports regex patterns (automatically escaped for literal search)
  • Shows first 20 results
  • Indicates match location (name/description/tags)

Tag Management

List all tags with counts:

cortex tag list

Output:

Tags:
  work (5)
  dev (4)
  production (3)
  personal (2)
  critical (2)

Add tags to entry:

cortex tag add "github-work" "urgent,security"

Output: Added 2 tag(s) to 'github-work'

Remove tags from entry:

cortex tag remove "github-work" "urgent"

Output: Removed 1 tag(s) from 'github-work'

Tag Rules:

  • Maximum 20 tags per entry
  • Maximum 30 characters per tag
  • Alphanumeric, hyphens, and underscores only
  • Automatically normalized (lowercase, sorted, deduplicated)
  • Case-insensitive duplicate detection

Password Generation

Default generation (16 chars, all types):

cortex pass

Custom generation:

cortex pass --length 20 --count 3

Selective character types:

cortex pass --length 12 --uppercase --digits

Options:

  • --length, -l: Password length (default: 16, min: 4, max: 128)
  • --count, -c: Number of passwords (default: 1, range: 1-50)
  • --uppercase, -u: Include uppercase letters
  • --lowercase, -w: Include lowercase letters
  • --digits, -d: Include digits
  • --special, -s: Include special characters (!@#$%^&*()_+-=[]{}|;:,.<>?)

Default behavior: If no flags specified, all character types enabled

Export Database

Export all passwords:

cortex export

Export template:

cortex export --template

Process:

  1. Master password authentication
  2. Security warning display
  3. Confirmation: "I understand this exports passwords in plain text"
  4. Export to cortex_export_[timestamp].json
  5. File permissions set to 0600 (Unix)

Output format (JSON):

{
  "version": "3.0.0",
  "timestamp": 1699999999,
  "entries": [
    {
      "name": "github-work",
      "password": "your_secure_password_123",
      "description": "Work GitHub account",
      "tags": ["work", "dev", "critical"]
    }
  ]
}

Template output (cortex_template.json):

{
  "version": "3.0.0",
  "timestamp": 1699999999,
  "entries": [
    {
      "name": "heisenberg",
      "password": "1AmTh3D4ng3r!",
      "description": "Say my name - I am the one who knocks",
      "tags": ["work", "critical"]
    }
  ]
}

Import Database

Basic import:

cortex import "backup.json"

Import with overwrite:

cortex import "backup.json" --overwrite

Process:

  1. File validation and parsing
  2. Entry validation (names, passwords, descriptions, tags)
  3. Master password authentication
  4. Batch import with progress
  5. Automatic rollback on failure

Validation rules:

  • Names: Non-empty, no __ prefix
  • Passwords: Minimum 4 characters
  • Descriptions: Maximum 500 characters, no password fragments
  • Tags: Maximum 20 per entry, valid format

Output:

Import Summary:
  Version: 3.0.0
  Timestamp: 1699999999
  Total entries: 15

Imported: entry1
Imported: entry2
Skipping 'entry3': already exists (use --overwrite to replace)

Import completed:
  Imported: 12
  Skipped: 2
  Failed: 1

Rollback: Automatic on errors, restores original entries

Master Password Management

Reset master password:

cortex reset

Process:

  1. Current master password authentication
  2. Automatic backup creation
  3. New password with complexity validation
  4. Re-encryption of all entries with new password
  5. Verification data update

Output: Master password reset successfully.

Security: All data re-encrypted, old sessions invalidated

Session Management

View current configuration:

cortex config show

Output:

Current Configuration:
  Session timeout: 480 seconds (8 minutes)

Set session timeout:

cortex config set-timeout 1800

Output: Session timeout set to 1800 seconds (30 minutes)

Range: 60 seconds (1 minute) to 86400 seconds (24 hours)

Clear session manually:

cortex lock

Output: Session cleared. You will need to authenticate again.

Session behavior:

  • Cached after first successful authentication
  • Validated on each command
  • Auto-expires after configured timeout
  • Machine-bound (cannot transfer between systems)
  • Secure file storage with 0600 permissions

Database Destruction

cortex purge

Security verification:

  1. Master password authentication
  2. Math puzzle: "This will permanently delete all stored passwords!"
  3. Equation example: (47 + 23) * 3
  4. Answer validation

Output: Database purged.

Effect: Permanent deletion of all data, backups preserved

Common Error Scenarios

# Database already exists
cortex init
# Output: "Database already exists. Use a different path or remove existing database."

# Database not initialized
cortex list
# Output: "Database not initialized. Use 'init' command."

# Duplicate entry creation
cortex create "existing-account"
# Output: "Account already exists. Use 'edit' to update or choose a different name."

# Weak master password
cortex init
# Master password: weak123
# Output: "Error: Your password needs improvement.
#          Missing: uppercase letter, special character"

# Short account password
cortex create "test"
# Password to store: abc
# Output: "Error: Password must be at least 4 characters"

# Password in description
cortex create "secure-app"
# Password: mySecretPass123
# Description: My password is mySecretPass123
# Output: "Error: Description cannot contain the password or parts of it."

# Invalid session timeout
cortex config set-timeout 30
# Output: "Error: Session timeout must be at least 60 seconds (1 minute)"

# Invalid clipboard timeout
cortex get "account" --clip 600
# Output: "Error: The time to be distracted is only allowed to be between 3 and 540 seconds"

# Invalid tags
cortex create "test" --tags "tag1,tag with space,tag3"
# Output: "Error: Tags can only contain alphanumeric characters, hyphens, and underscores"

# Too many tags
cortex create "test" --tags "tag1,tag2,...,tag21"
# Output: "Error: Maximum 20 tags allowed"

# Entry not found
cortex delete "nonexistent"
# Output: "Account 'nonexistent' not found."

# System entry protection
cortex delete "__init__"
# Output: "Error: Cannot delete system entries"

# Empty search pattern
cortex find ""
# Output: "Error: Search pattern cannot be empty"

# Import validation errors
cortex import "invalid.json"
# Output:
# Validation errors:
#   - entry1: Password must be at least 4 characters
#   - entry2: Description too long

Security Considerations

Input Validation

  • Master Password: Min 8 chars, complexity requirements
  • Account Password: Min 4 chars
  • Description: Max 500 chars, no password fragments
  • Tags: Max 20 per entry, 30 chars each, valid format
  • Search Pattern: Max 100 chars, max 10,000 entries processed

Session Security

  • Encryption: ChaCha20-Poly1305 with unique session key
  • Machine Binding: SHA256 hash of CPU brand
  • Timeout: Configurable (60s - 24h)
  • Max Age: Hard limit of 24 hours
  • Failed Attempts: Max 3 before session clear
  • File Security: Secure overwrite before deletion

Export Security

  • Confirmation: Plain text warning required
  • File Permissions: Restricted to owner (Unix)
  • Temporary Files: Written to .tmp first, then renamed
  • Error Handling: Failed exports cleaned up

Import Security

  • Validation: Comprehensive before any database changes
  • Rollback: Automatic on failure
  • Progress: Real-time feedback
  • Batch Safety: Transactional behavior

Password Security Requirements

Master Password

  • Minimum: 8 characters
  • Complexity: At least 3 of 4 types:
    • Lowercase letters (a-z)
    • Uppercase letters (A-Z)
    • Digits (0-9)
    • Special characters (!@#$%^&*()_+-=[]{}|;:,.<>?)
  • Validation: Checked during init and reset

Account Passwords

  • Minimum: 4 characters
  • Maximum: No limit (practical limit: 128 for input)
  • Restriction: Cannot appear in description field
  • Fragment Detection: Sliding window algorithm for partial matches

Technical Specifications

Cryptography

  • Cipher: ChaCha20-Poly1305
  • Key Size: 256 bits
  • Nonce: 96 bits (12 bytes), crypto-random
  • Tag: 128 bits (16 bytes), authenticated
  • Hash: BLAKE3, 256-bit output
  • KDF: BLAKE3^600000(password || salt || hardware_id)
  • Session KDF: BLAKE3^300000(hardware || constant || salt)

Storage

  • Engine: Sled embedded key-value store
  • Format: Binary (bincode serialization)
  • System Entries: Prefixed with __
    • __init__: Verification data
    • __salt__: 32-byte master salt
    • __config__: Serialized configuration
  • Backup Retention: Last 5 backups

Limits

  • Password Length: 4-128 characters (input), unlimited (storage)
  • Description: 500 characters
  • Tags: 20 per entry, 30 characters each
  • Search Pattern: 100 characters
  • Search Results: First 20 displayed
  • Search Processing: Max 10,000 entries
  • Session Timeout: 60 seconds to 24 hours
  • Max Session Age: 24 hours (hard limit)
  • Clipboard Timeout: 3-540 seconds
  • Password Generation: 4-128 characters, 1-50 count
  • Import Batch: Unlimited with validation

Performance

  • KDF Speed: ~300ms for 600,000 iterations (varies by CPU)
  • Session KDF: ~150ms for 300,000 iterations
  • Encryption: < 1ms per entry
  • Database: O(log n) lookups
  • Search: O(n) with early termination
  • Export: Buffered writes (64KB buffer), 1000-entry progress

Command Reference

Command Purpose Required Args Optional Args
init Initialize database None None
create <name> Create entry name --tags <tags>
get <name> Retrieve entry name --clip [seconds]
list List all entries None --tags (deprecated)
delete <name> Delete entry name None
edit <name> Edit entry name --tags <tags>
find <pattern> Search entries pattern -i, -n
tag list List all tags None None
tag add <name> <tags> Add tags name, tags None
tag remove <name> <tags> Remove tags name, tags None
pass Generate passwords None -l, -c, -u, -w, -d, -s
export Export database None --template
import <file> Import from JSON file --overwrite
reset Change master password None None
config show Show configuration None None
config set-timeout <sec> Set session timeout seconds None
lock Clear session None None
purge Destroy database None None

Troubleshooting

Session Issues

Problem: "Authentication failed" despite correct password Solution: Clear session and try again

cortex lock
cortex list

Problem: Session expires too quickly Solution: Increase timeout

cortex config set-timeout 3600  # 1 hour

Hardware Issues

Problem: "Decryption failed" after hardware change Solution: Export from backup, reinitialize, and import

# On old system:
cortex export

# On new system:
cortex init
cortex import cortex_export_[timestamp].json

Import Errors

Problem: Import validation errors Solution: Review JSON format and validation rules

# Generate template for reference
cortex export --template

# Check validation errors in output
cortex import file.json

Permission Issues

Problem: "Permission denied" on Unix Solution: Check file permissions

chmod 700 ~/.config/cortex
chmod 600 ~/.config/cortex/.password-store/*

Best Practices

Master Password

  • Use a unique, strong passphrase
  • Never store in plain text
  • Use password manager for backup (not Cortex itself)
  • Change periodically with reset command

Session Management

  • Set appropriate timeout for your workflow
  • Use lock when leaving workstation
  • Shorter timeouts for shared systems
  • Longer timeouts for personal, secure systems

Organization

  • Use descriptive entry names
  • Add meaningful descriptions
  • Tag entries consistently
  • Create tag hierarchy: work-dev, work-prod, personal-email

Backups

  • Export regularly to encrypted external storage
  • Test import process periodically
  • Keep backups on separate media
  • Automate with scripts if needed

Security

  • Use clipboard mode to avoid terminal history
  • Clear clipboard manually with Ctrl+C if needed
  • Don't share export files
  • Secure export files immediately (encrypt or delete)
  • Use purge to completely remove database

Clone this wiki locally