Find API keys and plan safe secret rotation

Autonomous secret-inventory and rotation planner for small LLM/operator stacks.

This pack answers a recurring operational problem: API keys, webhook tokens, model-provider credentials, and service secrets get copied into env files, scripts, ticket snippets, or old deployments, then nobody knows which owner must rotate what. The agent gives you a deterministic inventory check, a local leak scan, and a concrete rotation plan. If a local Claude/Kimi/Codex CLI is connected, it can also write a concise operator brief. Without a CLI, it remains fully useful offline.

Target users

• Solo operators running LLM agents on one or more Debian VMs.
• Small teams with shared .env files and provider credentials.
• Ops owners who need a repeatable weekly secret hygiene report.
• Agencies shipping white-label automations that must avoid credential drift.

Honest scope

The agent does not rotate secrets by itself unless you wire provider-specific commands in the inventory. Its default behavior is safer: detect, score, plan, and report. You decide when commands should run.

Quick Start

cd agent-secrets-rotate-v1
python3 -m venv venv
venv/bin/pip install -r requirements.txt

venv/bin/python agent.py init --inventory secrets_inventory.json
venv/bin/python agent.py scan \
  --inventory secrets_inventory.json \
  --path /srv/my-agent \
  --output reports/latest_rotation_report.json \
  --deterministic

The command writes:

• reports/latest_rotation_report.json
• reports/latest_rotation_report.md

Run python agent.py --help for every command.

One-Shot Debian Install

sudo bash install.sh

The installer creates a venv, installs stdlib-only requirements, detects an optional local LLM CLI, and installs a systemd timer-like service loop. Use bash install.sh --no-service for local-only setup.

Flow

        +---------------------+
        | secrets inventory   |
        | JSON owners/dates   |
        +----------+----------+
                   |
                   v
        +---------------------+        +---------------------+
        | deterministic risk  |<-------| local file scan     |
        | age/due/owner check |        | env/json/yaml/code  |
        +----------+----------+        +----------+----------+
                   |                              |
                   +--------------+---------------+
                                  v
        +---------------------+        +---------------------+
        | rotation plan       |------->| optional BYO-LLM    |
        | P0/P1/P2 steps      |        | operator brief      |
        +----------+----------+        +----------+----------+
                   |                              |
                   v                              v
        +----------------------------------------------------+
        | JSON + Markdown report for humans and automation   |
        +----------------------------------------------------+

Example Inventory

{
  "schema_version": 1,
  "secrets": [
    {
      "id": "billing-api",
      "provider": "billing-provider",
      "owner": "ops",
      "location": "env:BILLING_API_KEY",
      "criticality": "high",
      "last_rotated_at": "2026-01-01",
      "rotation_days": 90,
      "rotation_command": "billingctl keys rotate billing-api",
      "verification_command": "curl -fsS https://billing.example/health"
    }
  ]
}

Useful Commands

# Create inventory
python agent.py init --inventory secrets_inventory.json

# Check dates and missing owners only
python agent.py inventory --inventory secrets_inventory.json

# Scan multiple roots
python agent.py scan --inventory secrets_inventory.json --path /srv/app --path /etc/my-agent

# Continuous loop, every 6 hours
python agent.py run --inventory secrets_inventory.json --path /srv/app --interval 21600

# Force offline deterministic mode
python agent.py scan --inventory secrets_inventory.json --path . --deterministic

Outputs

The JSON report contains:

• summary.risk_score from 0 to 100.
• inventory_assessment[] with age, due date, status, and missing fields.
• findings[] with redacted matches only.
• rotation_plan[] with P0/P1/P2 steps.
• operator_brief from deterministic logic or BYO-LLM.

Safety Defaults

• No API key is requested by the pack.
• Secret-like values are redacted in reports.
• Large files, build folders, venvs, and git internals are skipped.
• Provider rotation commands are documented but not executed by default.
• Offline tests create throwaway temp files only.

Use a local model (Ollama)

The optional LLM step can also run on your own machine through Ollama, so no text leaves your server. No account and no API key.

ollama pull <model>               # any chat model you like
export PACK_LLM=ollama            # prefer Ollama even if a coding-agent CLI is installed
export PACK_OLLAMA_MODEL=<model>  # optional: default is the first chat model the server lists
python3 -c "import llm_adapter; print(llm_adapter.detect())"   # prints: ollama

• PACK_OLLAMA_HOST points to another server (default http://127.0.0.1:11434); OLLAMA_HOST is also read when PACK_LLM=ollama.
• PACK_OLLAMA_NUM_CTX sets the context size if your reports or prompts are long.
• Without PACK_LLM, a local Ollama server is used only when no Claude Code, Kimi Code or Codex CLI is found.
• If the server is down or the model is missing, the pack keeps working in its deterministic mode.

Learning memory (local and private)

Every LLM call this pack makes is journaled in ./.pack_memory/ next to the code, so the pack can improve for you. Nothing is ever sent anywhere.

• What is kept: the task name, the masked input, the masked answer, status and latency. Keys, tokens, e-mails, phone numbers, IP addresses, card and IBAN numbers and personal paths are masked before writing; the system prompt is never stored.
• Teach it: python3 pack_memory.py feedback last ok confirms a result, python3 pack_memory.py feedback last bad --fix "the right answer" corrects it. Confirmed and corrected runs are reused as validated examples when a similar input comes in. Unrated runs are never injected into a prompt.
• Find similar cases: python3 pack_memory.py similar "some text" and python3 pack_memory.py clusters (groups of near-identical failures) work in plain Python, no model needed. Optional meaning-based matching uses an embedding model you already run locally: python3 pack_memory.py enable-semantic (Ollama on this machine only).
• Share, only if you want: python3 pack_memory.py export writes an anonymised summary (counts, statuses, size buckets, no text) for you to review.
• Control: PACK_MEMORY=0 turns it off, PACK_MEMORY_STORE_TEXT=0 keeps fingerprints only, python3 pack_memory.py purge --yes wipes it.