Nex Keyring

Manage and track local API keys, secrets, and tokens with rotation status, risk levels, auditing, and policy enforcement without storing actual secret values.

Security Scan

The skill's code, instructions, and requested resources are consistent with a local key/rotation tracker that scans .env files and environment variables and stores metadata (not raw secret values), but there are minor documentation/code inconsistencies and at least one coding bug you should review before installing.

Purpose & Capability

The name/description match the implementation: the package scans .env files and environment variables, detects service patterns, records metadata (name, prefix, SHA256 hashes if provided), tracks rotation history and audit logs, and stores everything under ~/.nex-keyring in SQLite. There are no unexpected cloud credentials or unrelated external services requested.

Instruction Scope

SKILL.md and the code direct the tool to read .env files and environment variables (intentional and expected). The implementation generally avoids storing actual secret values (it stores presence, prefixes and hashes), but scanning environment variables and files is inherently sensitive — ensure you understand the privacy implications and that the agent or the person running setup is trusted.

Install Mechanism

There is no remote install step or external download; installation is via the included setup.sh which writes files under the user's home (~/.nex-keyring) and creates a wrapper in ~/.local/bin. No network fetching or third‑party installers are invoked. Note: the setup script initially writes a wrapper with a hardcoded path then rewrites it to use SKILL_DIR; this looks odd but the final wrapper is created from the local skill directory.

Credentials

The skill declares no required environment variables or external credentials (consistent with purpose). README mentions optional env overrides (NEX_KEYRING_HOME, NEX_KEYRING_DB) not visible in the provided code — a small documentation/code mismatch. The code does inspect os.environ to detect keys (expected), but it does not appear to exfiltrate environment contents.

Persistence & Privilege

The skill does not request global/system privileges or 'always' inclusion. It stores files under the user's home and creates a user-level CLI wrapper (~/.local/bin). It does not modify other skills or system-wide configs beyond that user-level install.

Assessment

This package appears to do what it claims: locally scan .env files and environment variables, track key metadata and rotation history, and avoid storing actual secret values. Before installing or running setup.sh, consider: 1) Review the setup.sh wrapper path that is written — ensure it points to the skill files on your machine (it tries to locate SKILL_DIR but double-check). 2) The tool reads environment variables and .env files — only run it in contexts where you trust the host and operator, and avoid running on machines with untrusted processes. 3) There are small code/documentation inconsistencies (README mentions env overrides that aren't evident in the code) and at least one apparent coding bug (truncated/undefined variable in storage.list_secrets that may cause runtime errors). I recommend auditing the code locally (especially storage.list_secrets and any truncated sections), running setup.sh in a controlled environment or container, installing the cryptography package if you want Fernet encryption, and backing up any sensitive files before first run. If you want higher assurance, ask the author for a complete, non-truncated source and unit tests demonstrating behavior (or run it in an isolated VM/container).

Local API key and secret rotation tracker. Monitor and manage all your API keys, webhooks, and credentials in one place. Track rotation status, detect stale keys, and enforce security policies. All data stays securely on your machine.

When to Use

Use this skill when the user asks about:

• API keys, secrets, tokens, or credentials
• Key rotation, rotation status, or rotation policies
• Which API keys haven't been rotated recently
• Stale or overdue credentials
• Tracking API keys from specific services (OpenAI, Cloudflare, Firebase, etc.)
• Scanning .env files for secrets
• Importing keys from environment files
• Security audit or credential management
• Credential expiration or rotation history
• Monitoring webhook or database secrets
• Password, wachtwoord, sleutel (Dutch for "key")
• API security or secret management

Trigger phrases: "API key", "secret rotation", "which keys need rotation", "stale credentials", ".env file", "rotate key", "track secrets", "credential management", "security audit", "API token", "webhook", "database password", "rotation status", "scan environment"

Quick Setup

If the database does not exist yet, run the setup script:

bash setup.sh

This creates the data directory (~/.nex-keyring), initializes the database, and verifies dependencies.

Available Commands

The CLI tool is nex-keyring. All commands output plain text.

Add a Secret

Register a new API key or secret:

nex-keyring add --name "OpenAI API Key" --service openai --category API --env-var OPENAI_API_KEY --rotation 90
nex-keyring add --name "Cloudflare Token" --service cloudflare --description "Production API token" --rotation 180
nex-keyring add --name "Database Password" --service postgresql --category DATABASE --used-in "production app"

Options:

• --name (required): Secret name (must be unique)
• --service: Service name (e.g., openai, cloudflare, firebase)
• --category: API, DATABASE, SSH, OAUTH, WEBHOOK, SMTP, DNS, HOSTING, AI, PAYMENT, OTHER
• --env-var: Environment variable name to track (e.g., OPENAI_API_KEY)
• --rotation: Rotation policy in days (default: 90, or service preset)
• --description: Human-readable description
• --tags: Comma-separated tags for organization
• --used-in: Project or script names using this key

List Secrets

Show all tracked secrets:

nex-keyring list
nex-keyring list --service openai
nex-keyring list --category API
nex-keyring list --category DATABASE

Show Secret Details

Display detailed information (never shows actual key values):

nex-keyring show "OpenAI API Key"
nex-keyring show "Cloudflare Token"

Shows:

• Service and category
• Creation and last rotation dates
• Rotation policy and days since rotation
• Risk level (FRESH, OK, STALE, CRITICAL)
• Environment variable tracking
• Usage context

Check Rotation Status

Check which keys need rotation:

nex-keyring check
nex-keyring check --service openai
nex-keyring check --all

Reports overdue and stale keys with:

• Days since last rotation
• Risk level assessment
• Rotation recommendations

Mark as Rotated

Record a rotation event:

nex-keyring rotate "OpenAI API Key"
nex-keyring rotate "OpenAI API Key" --hash abc123def456... --notes "Routine rotation"

The tool prompts for the new key hash if not provided. Hash is used to detect key changes without storing the actual key.

Scan Environment

Scan .env files or environment variables for API keys:

nex-keyring scan --env-file .env
nex-keyring scan --env-file /path/to/.env.production
nex-keyring scan --environment

Detects:

• Known service patterns (OPENAI_, CF_, FIREBASE_, etc.)
• Whether values are set
• Key names for tracking

Import from .env

Auto-register all keys from a .env file:

nex-keyring import .env
nex-keyring import .env.production --auto-register

Creates tracked secrets for each detected key with appropriate service detection and rotation policies.

Show Stale/Overdue Keys

List all keys needing attention:

nex-keyring stale

Shows:

• Stale secrets (>90 days without rotation)
• Overdue secrets (past their rotation policy)
• Days since last rotation
• Risk levels

View Rotation History

Check rotation history for a specific key:

nex-keyring history "OpenAI API Key"
nex-keyring history "Cloudflare Token"

Displays:

• All rotation events with dates
• Who/what rotated the key (manual/auto)
• Rotation notes

Export Secrets

Export secret registry (metadata only, never actual keys):

nex-keyring export --format json
nex-keyring export --format csv --output registry.csv
nex-keyring export --format markdown --output registry.md

Formats: JSON, CSV, Markdown (metadata only, no sensitive data)

View Audit Log

Show all actions on tracked secrets:

nex-keyring audit
nex-keyring audit --limit 100
nex-keyring audit --secret "OpenAI API Key"

Tracks:

• All secret accesses
• Rotation events
• Creation and deletion
• Modifications

Statistics

Overview of tracked secrets:

nex-keyring stats

Shows:

• Total tracked secrets
• Stale and overdue counts
• Breakdown by category and service

Configuration

Show system configuration:

nex-keyring config

Displays:

• Data storage location
• Encryption method
• Default rotation policies
• Service presets

Data Security

• No key storage: Never stores actual API key values, only hashes for change detection
• Local only: All data stored in ~/.nex-keyring, never transmitted
• Encryption: Uses Fernet (recommended) or base64 obfuscation if cryptography unavailable
• Audit trail: Complete audit log of all access and modifications
• Safe exports: Exported data contains metadata only, no sensitive values

Service Presets

Automatic rotation policies for common services:

• Cloudflare: 180 days
• OpenAI: 90 days
• Resend: 90 days
• Firebase: 180 days
• GitHub: 90 days
• TransIP: 365 days
• DashScope/Qwen: 90 days
• Stripe: 90 days
• Telegram: 365 days

Custom policies can be set per secret.

Risk Levels

Secrets are assessed based on time since last rotation:

• FRESH: < 30 days (green status)
• OK: 30-90 days (normal)
• STALE: 90-180 days (warning)
• CRITICAL: > 180 days (action required)

Examples

Scenario: Onboard new API keys

# Scan your .env file
nex-keyring scan --env-file .env

# Import all found keys
nex-keyring import .env

# Review what was added
nex-keyring list

# Check current rotation status
nex-keyring check

Scenario: Identify overdue keys

# Show all stale and overdue secrets
nex-keyring stale

# Check specific service
nex-keyring check --service stripe

Scenario: Rotate a key

# Show current details
nex-keyring show "OpenAI API Key"

# After rotating the key in OpenAI dashboard:
nex-keyring rotate "OpenAI API Key" --notes "Monthly rotation"

# Verify rotation was recorded
nex-keyring history "OpenAI API Key"

Scenario: Export for audit

# Export metadata for security review
nex-keyring export --format csv --output audit_$(date +%Y%m%d).csv

# View rotation history for compliance
nex-keyring audit --limit 200

Dependencies

• Python 3.8+
• SQLite3 (built-in)
• Optional: cryptography (for Fernet encryption, recommended)

Install cryptography for stronger encryption:

pip install cryptography

Without it, keys are obfuscated with base64 (not recommended for production).

---

Built by Nex AI | MIT-0 License