Agent Secrets Rotate v1

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.