agentleFS
mdostalmdostal/portunus/.claude/skills/portunus-vault-audit/SKILL.md

portunus-vault-audit

Skill2 starsChanged 32 days agoMITView on GitHub

Bundle missing-metadata context for the vault (crawl), render current vault state as a deploy-docs report, or run a leak-scan over the human-configured local paths and check/clear findings. Use when the user asks you to "check the vault," "see what's missing," "generate deploy docs," "scan for leaked secrets," or "check if anything leaked" -- never to fetch or handle a secret's actual value, which this skill never touches.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Scan paths are never auto-configured: Before a scan finds anything, paths must be explicitly added:

    line 55
  2. Very specific:

    Do not wire this to auto-rotate or auto-block anything — v1 is advisory-only by design (docs/architecture.md §11).

    line 96

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Portunus Vault Audit

Thin wrapper around three read-mostly Portunus operations that all answer "what's the state of the vault, and does anything need attention" rather than resolving/injecting a value: crawl (metadata gaps), report (a Markdown deploy-docs snapshot), and leak-scan (has a managed secret's value shown up somewhere it shouldn't). None of these ever return, print, or need you to handle a secret value.

When to use

  • "What's missing from the vault's metadata?" / "help me fill in descriptions" -> crawl.
  • "Generate deploy docs for this vault" / "what secrets does this project use and why" -> report.
  • "Check if any of our secrets leaked into logs/chat history/.claude" / "scan for leaks" -> leak-scan.
  • "Is <reference> still flagged as leaked?" / "I rotated it, clear the warning" -> leak status / mark-rotated.

When NOT to use

  • You need to fetch or inject a secret's actual value — use portunus-ask instead. This skill never resolves a value.
  • You need to store a brand-new secret — use portunus-drop.
  • You need to configure which backend a project uses — use portunus-vault-setup.

Crawl — metadata-gap discovery, never automatic

portunus crawl --json                 # every reference missing description/purpose/org
portunus crawl --org <org> --json     # scoped

This bundles context (sm_name, group, project, org, repo, its vault/rotation binding) for YOU to read and propose values from — it never calls an LLM itself and never writes anything. If you have a real proposal for a field, call portunus metadata confirm (or the portunus_suggest_metadata MCP tool) — never edit registry.json directly.

Report — a real deploy-docs starting point

portunus report                        # prints Markdown to stdout
portunus report --out deploy-docs.md    # writes to a file
portunus report --org <org>             # scoped

Independent of crawl — useful immediately, with or without any crawl-sourced metadata.

Leak-scan — advisory only, never blocks anything

Scan paths are never auto-configured. Before a scan finds anything, paths must be explicitly added:

portunus leak-scan config show                      # what's currently configured (often empty)
portunus leak-scan config add-path '<glob>'          # e.g. ~/.claude/projects/**/*.jsonl
portunus leak-scan config remove-path '<glob>'

Then:

portunus leak-scan --json      # run a scan; exits 1 if new findings exist, 0 otherwise
portunus leak status           # severity + finding counts for every reference with findings
portunus leak status <name>    # for one reference
portunus leak mark-rotated <name>   # after YOU (or the user) have actually rotated it

This is a detective control, not a preventive one. It finds secrets that already leaked into the paths you've configured; it does nothing to stop the next paste into a chat window, and it never blocks resolve/inject. The output ever contains only {ref_name, path, line_number, severity} — never the leaked value itself and never a surrounding excerpt. mark-rotated is your own assertion that you rotated the credential — Portunus cannot verify that independently, and a later scan will still re-flag the reference if the old value is genuinely still present somewhere.

MCP equivalents (for a harness that isn't this CLI session, or fully automated pipelines): portunus_crawl_candidates, portunus_leak_status, portunus_run_leak_scan, portunus_leak_scan_config_show/add_path/remove_path, portunus_leak_mark_rotated. Same gating, same never-a-value guarantee as the CLI above.

Scheduling a scan (cron/CI)

portunus leak-scan is already cron/CI-ready: it exits 1 when new findings exist and 0 otherwise, and never prompts. A simple periodic check (see README.md's "Scheduling leak-scan" section for a full cron/launchd example):

0 9 * * * PORTUNUS_HOME=/path/to/home portunus leak-scan --json >> /path/to/leak-scan.log 2>&1

Do not wire this to auto-rotate or auto-block anything — v1 is advisory-only by design (docs/architecture.md §11).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.