secretzero-author

name: secretzero-author description: | Use when authoring, reviewing, or walking a user through a new or existing Secretfile.yml. Guided session: manifest root, inventory table, optional local discovery, add/edit loop with secret-type and target menus, validate, optional secretzero web. Hermes + MCP notes included. Safe contextless discovery, .szvar lanes, policy-bound targets. Inherits absolute rule from skills/secretzero/SKILL.md. Co-load skills/secretzero-handle/SKILL.md for .env / spill-safe CLI.

SecretZero Author Skill

Use this skill whenever the task is to create or improve Secretfile.yml and related .szvar files.

Absolute rule (non-negotiable): see skills/secretzero/SKILL.md — never consume secrets in agent context; route all secret operations through SecretZero (detect/discover, validate, sync, web UI, agent sync). Do not ask users to paste values into chat.

For new manifests, updates to existing manifests, or Hermes / MCP-driven authoring, follow Guided authoring session below.

Mission

Produce high-quality, json-schema compliant SecretZero manifests that:

• Pass secretzero validate with zero issues.
• Keep discovery and inventory contextless (metadata only; SecretZero commands, not file reads).
• Intelligently break out environment variance into .szvar files.
• Bind provider-backed targets to least-privilege identity policies for AWS/Azure/other authenticated environments.

Capability discovery (generators & targets)

Use the live catalog before inventing secrets[].kind or targets[].kind values.

Primary (machine-complete — preferred for agents):

secretzero catalog --format json
secretzero catalog --provider gitlab --format json
secretzero catalog --bundle core --format json
secretzero catalog --kind gitlab_variable --kind-type target --verbose

The catalog is backed by BundleRegistry and includes every registered generator, target, and provider bundle with typical_generators hints per target.

Human-readable summary:

secretzero catalog
secretzero secret-types

Manifest-scoped (already configured in this Secretfile — not the global catalog):

secretzero list providers -f <manifest_root>/Secretfile.yml --format json
secretzero list targets -f <manifest_root>/Secretfile.yml --format json

Provider introspection:

secretzero providers list
secretzero providers capabilities <provider_kind>

The static decision map below is a curated shortcut; when it disagrees with secretzero catalog --format json, trust the catalog.

Safety Rules (Non-Negotiable)

Inherits the SecretZero only — never secrets in context rule from skills/secretzero/SKILL.md.

• Never ask for, copy, log, or output plaintext secret values in chat, prompts, or tool results.
• Never use IDE/filesystem/MCP tools to read files that may contain secrets; use detect / discover / list / status instead.
• Discovery and inventory use metadata only (status, test, provider identity, list secrets JSON) — not get --reveal or manifest render.
• Human entry for missing values: secretzero web or secretzero agent sync --web — not chat paste.
• If provider identity evidence is missing, mark policy confidence as low and require human confirmation.

Guided authoring session

Use this flow for new or existing manifests. Phases 0–1 apply to both; Phase 2 onward supports agent-assisted add/edit loops after discovery or whenever the user wants to extend secrets[].

Do not skip steps unless the user explicitly says they already decided (then record their choice and continue).

Phase 0 — Confirm manifest root (required, always first)

Before naming secrets or picking generators, confirm the manifest root with the user:

Ask explicitly:

1. Absolute path to the manifest root (default: current project/repo root if obvious).
2. Whether Secretfile.yml already exists there (edit vs create).
3. Default local target base for provider: local / kind: file paths — almost always the manifest root (.). If secrets should land under a subfolder (e.g. config/, secrets/), confirm that once and use it consistently in config.path (paths are relative to the manifest root unless absolute).

Rules:

• Do not draft config.path values until manifest root and local base folder are confirmed.
• Repeat the chosen root in one line before presenting secret-type options (e.g. “Manifest root: /path/to/app, local files under .”).
• If the user points at a monorepo subproject, use that directory as manifest root, not the repo apex, unless they want a shared top-level manifest.

Phase 1 — Offer local discovery (optional)

Offer discovery when it helps; skip when the project is greenfield with no env files yet.

Offer this prompt:

I can scan the manifest root for existing secret names (no values) and suggest manifest entries. Use local discovery? (yes / no)

After discovery:

• Present results as a table of names (and source file paths only) — never paste values from disk into chat.
• Ask which candidates to include in secrets[] (multi-select or “all above threshold”).
• Merge chosen rows into the manifest using placeholders (null leaves, ${VAR}) — not literals. Co-load skills/secretzero-handle/SKILL.md when .env preseed is next.
• If Secretfile.detect.yml was written, treat it as a draft; human reviews before rename/replace to Secretfile.yml.

Never read_file on .env, .env.*, *.pem, or lane .szvar files in agent sessions.

Phase 2 — Show current manifest inventory (existing or after first draft)

Whenever Secretfile.yml exists (or you just merged discovery drafts), show what is already defined before adding more entries. This phase applies to updates as well as greenfield manifests that already have rows.

Load metadata (no values):

secretzero list secrets -f <manifest_root>/Secretfile.yml --format json
secretzero status -f <manifest_root>/Secretfile.yml --format json   # optional: synced / not_synced

Present visually in chat — use a clear markdown table (and optional compact mermaid summary when ≤8 secrets):

Rules:

• Include name, kind, targets (provider/kind), and status when status --format json was run.
• Do not include secret values, static defaults, or full target config blobs in chat (use SZ_AGENT_MODE when editing existing manifests under an agent).
• If the manifest is empty, say so explicitly and skip straight to Phase 3.

Offer:

Here is your current Secretfile inventory. Add another secret, edit an existing one, or continue to validate? (add / edit / done)

Phase 3 — Add / edit loop (repeat until user says done)

This loop is the main agent-assisted authoring path for both new and existing manifests. Run it after Phase 1 merges discovery candidates, or anytime the user wants to extend the manifest without rescanning disk.

Loop prompt (each iteration):

Add a new secret, modify an existing entry, or finish manifest edits? (add / edit name / done)

When the user chooses add or edit:

1. Destination category (numbered menu):

   #	Category	Typical providers / targets
   1	Local disk	provider: local → file or template
   2	Cloud / platform API	aws, azure, vault, github, …
   3	Encrypted in git	sops / git_crypt / ansible_vault file targets

2. Refresh live capability lists (once per iteration or when the user changes destination):

   secretzero catalog --format json
   secretzero catalog --provider <provider_kind> --format json
   secretzero catalog --kind <kind> --kind-type generator --verbose
   secretzero catalog --kind <kind> --kind-type target --verbose
   secretzero list providers -f <manifest_root>/Secretfile.yml --format json
   secretzero list targets -f <manifest_root>/Secretfile.yml --format json
   

3. Generator menu (secrets[].kind) — present as lettered options (run secretzero catalog --format json for the full list):

   Option	kind	Use when
   A	random_password	High-entropy password
   B	random_string	API keys, tokens, alphanumeric secrets
   C	static	Human prompt, ${VAR}, or structured dict leaves
   D	script	Generate via command (ssh-keygen, etc.)
   E	azure_app_reg	Entra app registration-shaped fields
   F	github_pat	Create GitHub App installation token via API
   G	entra-agent-blueprint	Agent Identity blueprint lifecycle
   H	gitlab_project_token	Create GitLab project access token via API
   I	provider_backed	Advanced; only if no bundle-specific kind fits

4. Target menu — from secretzero catalog --format json (bundle targets + typical_generators) and the Decision map; for local, offer dotenv / json / yaml / toml / tfvars / template options.

5. Per-entry checklist: name, generator, target(s) (paths relative to manifest root), .szvar lane variance, identity_policies on cloud targets.

6. Apply the edit to Secretfile.yml (and .szvar if needed), then re-run Phase 2 (refresh inventory table) before the next iteration.

Stop the loop when the user chooses done or confirms the inventory is complete.

Phase 4 — Validate

1. secretzero validate -f <manifest_root>/Secretfile.yml
2. secretzero sync --dry-run -f … (and --var-file when lanes exist)
3. Fix schema/policy errors; re-show inventory if secrets were renamed or removed.

Phase 5 — Optional operations UI and seeding handoff

After a clean validate (and dry-run when providers exist), offer two separate checkpoints (do not merge in one step):

A — Network dashboard (optional, human-operated sync UI)

Start the SecretZero web dashboard in the background so you can sync, refresh, and edit static values in the browser? (yes / no)

If yes (trusted local machine only):

cd <manifest_root>
secretzero web -f Secretfile.yml --host 127.0.0.1 --port <free-port> \
  > /tmp/secretzero-web.log 2>&1 &

• Use 127.0.0.1 unless the user explicitly needs LAN access.
• Relay the full login URL and bootstrap token from command output or log — never paraphrase the token.
• Tell the user this is the persistent dashboard (secretzero web), not the one-shot Vector 2 form from secretzero agent sync --web.
• Remind them to use Shut down in the UI or stop the background job when finished.

B — Agent seeding (when values are still missing)

Load skills/secretzero-agent/SKILL.md for secretzero agent sync --json (and --web only for the one-shot localhost seeding form). Prefer the Phase 5A dashboard when the human wants a full UI; prefer agent sync when the agent should stay structured and metadata-only.

Hermes + MCP

The guided phases are transport-agnostic; only the invocation changes.

MCP notes:

• This repo ships CLI + REST API, not a first-party MCP server. Bridges expose subprocess tools; tool names may differ from CLI flags.
• detect / discover are CLI-only today — MCP authoring should call those commands, not Hermes filesystem reads of .env.
• Do not use MCP sampling/createMessage for discovery. Use SecretZero detect / discover (metadata-only JSON). Sampling sends file context to the host LLM and increases spill risk versus purpose-built scanners.
• Leave sampling disabled on untrusted SecretZero MCP bridges unless you operate a custom server with an explicit spill policy.
• With SZ_AGENT_MODE=true, co-load skills/secretzero-handle/SKILL.md; inventory and validate still work; avoid render and plaintext dumps.

Definition of done (guided session)

• Manifest root and local path base were confirmed with the user.
• Current secrets[] were shown in a readable inventory table before and after edits.
• Add/edit loop ran until the user said done; kinds/targets chosen from menus + CLI lists, not invented.
• Discovery was offered when appropriate; if run, only metadata was shown in chat.
• secretzero validate passes; dry-run sync attempted when providers are configured.
• User was offered secretzero web (background, localhost) and/or secretzero-agent seeding, as separate optional steps.

Install / Verify

Preferred:

uv tool install -U "secretzero[all]"

Targeted extras (install only what you author against):

Verify:

secretzero --help
secretzero validate --help
secretzero catalog --format json
secretzero providers list

Live bundle matrix (targets only): docs/reference/provider-bundles-auto.md — supplement with secretzero catalog --format json for generators.

Decision map: where should this secret go?

Start with the destination, then pick provider → target kind → generator kind.

flowchart TD
  Q["Where must the secret live?"]
  Q --> L["Local disk / repo-adjacent file"]
  Q --> C["Cloud or platform API"]
  Q --> E[Encrypted in git]
  L --> LF["provider: local"]
  LF --> F1["kind: file — pick format"]
  LF --> F2["kind: template — Jinja2 render"]
  C --> CP[Pick provider bundle row below]
  E --> EP["sops / git_crypt / ansible_vault file targets"]

Local provider (provider: local)

No providers: entry required. Use for dev, CI artifacts, Terraform var files, and blueprint metadata sidecars.

tfvars v1 limits: flat name = "string" only; gitignore *.tfvars; use key when manifest secret name ≠ Terraform variable name. See examples/terraform-tfvars/.

Provider bundles (sync targets)

Core generators (any provider)

Bundle-specific generators

Static-like kinds (static, azure_app_reg, …): agent sync may prompt per null leaf; prefer .szvar to pre-fill lane values.

Multi-target pattern

Same secret, multiple destinations (common):

targets:
  - provider: aws
    kind: ssm_parameter
    config: { name: /${env}/db/password }
  - provider: local
    kind: file
    config: { path: .env, format: dotenv, merge: true, key: DB_PASSWORD }

Attach identity_policies on cloud targets when sync must be lane-bound (see below).

Authoring Workflow

For interactive, Hermes, or MCP work, use Guided authoring session (inventory + add/edit loop). For quick expert edits without a walkthrough, use this checklist:

1. Load schema context
   • Treat Secretfile.schema.json and src/secretzero/models.py as source of truth.
2. Confirm manifest root (if paths or -f may change)
   • Same rules as Phase 0 in guided session.
3. Use the decision map
   • Pick destination → provider/target → generator before writing YAML.
4. Model whole secrets first
   • One logical secret per secrets[] entry unless a true multi-field bundle is needed.
5. Select generator intentionally
   • Prefer random_password, random_string, static (or static-like kinds) before script / provider_backed.
6. Map explicit targets
   • Every secret has clear targets unless intentionally deferred (e.g. Entra blueprint metadata-only phase).
7. Break out environment variance
   • Keep structural defaults in Secretfile.yml.
   • Move lane-specific values to *.szvar files (dev.szvar, staging.szvar, prod.szvar).
8. Apply identity guardrails
   • Add kind: provider_identity policies and attach with identity_policies where needed.
9. Validate in loop
   • secretzero validate
   • secretzero render (if interpolation/templating is used)
   • secretzero sync --dry-run --var-file <lane>.szvar

Environment Breakout Heuristics (.szvar)

Prefer .szvar breakout when values differ by deployment lane:

• Target names/paths (/${env}/...)
• Regions, accounts, tenants, namespaces
• Role/session specific selectors
• Non-structural per-lane toggles
• Pre-filled static / azure_app_reg leaves (avoid re-prompts)

Keep in manifest:

• Secret definitions (name, kind, generator config shape)
• Provider aliases and auth mode intent
• Policy object structure

Pattern:

variables:
  env: dev
  aws_region: us-east-1

dev.szvar:

env: dev
aws_region: us-east-1

prod.szvar:

env: prod
aws_region: us-west-2

Contextless Secret Discovery (Safe Mode)

Use only discovery commands that return metadata (no secret values):

# Local repo scan (names / paths only)
secretzero detect <manifest_root> --all-keys --format json
secretzero discover <manifest_root> --local-only --dry-run --format json

# Provider / lockfile metadata (existing manifest)
secretzero status --format json
secretzero test --verbose --format json
secretzero catalog --format json
secretzero list providers -f Secretfile.yml --format json
secretzero list targets -f Secretfile.yml --format json

Derive policy candidates from actor/auth metadata (account, region, arn, tenant_id, subscription_id, namespace, etc.), never from secret contents.

Guided session: offer detect / discover in Phase 1; use this section for provider-identity policy drafting on an existing manifest.

Target Policy Binding Guidance

• AWS: constrain account and region first; optionally constrain role/arn patterns.
• Azure: constrain tenant_id and, when available, subscription_id.
• Other providers: bind to strongest stable identity fields exposed by get_actor_info().
• Avoid broad * or permissive regex unless explicitly approved.

Example:

policies:
  aws_prod_identity:
    kind: provider_identity
    providers: [aws]
    match: all
    rules:
      - field: account
        glob: "111111111111"
      - field: region
        glob: us-east-1

Related skills & examples

Definition of Done

• Manifest root (and local path base) were confirmed for new manifests.
• Secretfile.yml is schema compliant and readable.
• Provider/target/generator choices match the decision map (or document intentional exceptions).
• secretzero validate exits cleanly.
• .szvar files cover lane variance without duplicating manifest structure.
• Provider-backed targets are bound to least-privilege identity policies where supported.
• No plaintext secret material appears in prompts, logs, files, or responses.