From e75388ef8655fd5374efa3312fc39ac4e45c68f2 Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Thu, 4 Jun 2026 17:10:17 -0500 Subject: [PATCH 01/10] fix: better author flow --- .cursorrules | 3 + .github/workflows/docs.yaml | 12 + .github/workflows/test.yaml | 19 ++ .mex/ROUTER.md | 4 +- .mex/context/setup.md | 3 +- .mex/patterns/INDEX.md | 1 + .mex/patterns/docs-links-lychee.md | 36 +++ .mex/patterns/secretfile-authoring.md | 4 +- .pre-commit-config.yaml | 6 + AGENTS.md | 5 +- README.md | 1 - Taskfile.yml | 10 + docs/examples/index.md | 2 +- docs/examples/jenkins-credentials.md | 6 +- docs/examples/repository.md | 17 +- docs/getting-started/index.md | 2 +- docs/getting-started/installation.md | 2 +- docs/getting-started/quickstart.md | 2 +- docs/index.md | 2 +- docs/reference/changelog.md | 2 +- docs/reference/faq.md | 4 +- docs/reference/troubleshooting.md | 2 +- docs/user-guide/configuration/validation.md | 2 +- docs/user-guide/index.md | 2 +- docs/user-guide/providers/azure.md | 2 +- docs/user-guide/providers/jenkins.md | 2 +- docs/user-guide/targets/jenkins.md | 2 +- lychee.toml | 17 ++ mise.toml | 1 + scripts/agent.pre-commit.sh | 4 + skills/secretzero-agent-adopt/SKILL.md | 3 +- skills/secretzero-agent/SKILL.md | 2 +- skills/secretzero-author/SKILL.md | 246 ++++++++++++++++++-- skills/secretzero-handle/SKILL.md | 2 + skills/secretzero/SKILL.md | 25 +- 35 files changed, 401 insertions(+), 54 deletions(-) create mode 100644 .mex/patterns/docs-links-lychee.md create mode 100644 lychee.toml diff --git a/.cursorrules b/.cursorrules index 33f6781..e525bb5 100644 --- a/.cursorrules +++ b/.cursorrules @@ -12,6 +12,7 @@ A secrets-as-code management tool that validates, generates, syncs, and tracks p ## Non-Negotiables - Never commit plaintext secrets, API keys, or credentials. - Never log or persist secret values outside approved providers/targets and lockfile metadata hashes. +- **Agents:** never consume secrets in context — use SecretZero only (`skills/secretzero/SKILL.md` absolute rule). - Use Pydantic v2 APIs only (`model_dump()` / `model_dump_json()`), not v1 methods. - Use Rich console output for CLI UX (`Console.print()`), not raw `print`. - Register new provider/generator/target capabilities through bundle manifests and the bundle registry. @@ -44,6 +45,8 @@ At the end of any coding task, run a fast local gate: ./scripts/agent.pre-commit.sh --mode fast --quiet ``` +The gate includes `task docs:links` (lychee on `README.md` and `docs/`). After doc edits, you can run `task docs:links` alone for a quick check. + Before any push/merge, run the full gate: ```bash diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 03c8ec4..ffdf4b8 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -31,6 +31,18 @@ jobs: run: | uv sync --frozen --all-extras + - name: Install lychee + env: + LYCHEE_VERSION: v0.24.2 + run: | + curl -fsSL \ + "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_VERSION}/lychee-x86_64-unknown-linux-gnu.tar.gz" \ + | tar xz + install -m 755 lychee /usr/local/bin/lychee + + - name: Check README.md and docs/ hyperlinks + run: lychee --config lychee.toml README.md docs/ + - name: Export Secretfile schema for docs run: | uv run secretzero schema export --output docs/Secretfile.schema.json diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index fd7d29b..997a946 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -14,6 +14,25 @@ permissions: contents: read jobs: + docs-links: + name: Docs hyperlink check (lychee) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Install lychee + env: + LYCHEE_VERSION: v0.24.2 + run: | + curl -fsSL \ + "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_VERSION}/lychee-x86_64-unknown-linux-gnu.tar.gz" \ + | tar xz + install -m 755 lychee /usr/local/bin/lychee + lychee --version + + - name: Check README.md and docs/ + run: lychee --config lychee.toml README.md docs/ + schema-doc-parity: name: Schema/Docs Parity runs-on: ubuntu-latest diff --git a/.mex/ROUTER.md b/.mex/ROUTER.md index 2d9cc19..94aa363 100644 --- a/.mex/ROUTER.md +++ b/.mex/ROUTER.md @@ -54,7 +54,8 @@ Then read this file fully before doing anything else in this session. - **Safe provider retrieval CLI:** `secretzero get` now retrieves via provider bundle methods (`SyncEngine.get_provider_secret`) with metadata-first output by default; plaintext requires `--reveal`. Sandbox policy guards retrieval when `SZ_SANDBOX=true` unless explicitly overridden by `SZ_ALLOW_GET_IN_SANDBOX=true`, and command-level policy preflight blocks on policy errors. - **GitNexus / MetaGit relational intel:** `secretzero sync` and `secretzero get` write `.gitnexus/secrets_overlay.json` (Ladybug-oriented JSON linking manifest secret names to symbol IDs / FQNs from `.gitnexus/discovery_bindings.json`). Optional `SZ_METAGIT_REGISTRY=1` merges inventory into `~/.metagit.yml`. `secretzero discover` persists bindings and extends LLM output with parent symbol / FQN fields. `secretzero gitnexus blast-radius --symbol ` wraps GitNexus impact; `secretzero rotate --trigger-reindex` runs `gitnexus analyze --skills` after success. Per-secret `process_tags` labels execution-flow sensitivity (schema + docs updated). - **Terraform static-variable behavior:** Terraform export now always emits sensitive input variables for static-like secrets (`static` and bundle kinds with `PROMPTS_LIKE_STATIC`, such as `azure_app_reg`). `--include-static-secrets` now controls whether static defaults are embedded as Terraform variable defaults. -- **Agent skill guidance split:** SecretZero guidance is now split into focused skills — `skills/secretzero-author/SKILL.md` (schema-compliant Secretfile authoring, safe contextless discovery, `.szvar` lane breakout, and policy-bound targets), `skills/secretzero-agent/SKILL.md` (agentic vectors, runtime/API workflows, and installation/onboarding), `skills/secretzero-handle/SKILL.md` (`SZ_AGENT_MODE`, `.env`/ingest preseed, spill-safe CLI), and `skills/secretzero-agent-adopt/SKILL.md` (Hermes/OpenClaw `agent list` / `agent adopt` bootstrap and restore loops). +- **Agent absolute rule (skills):** `skills/secretzero/SKILL.md` — never consume secrets in LLM/tool context; use SecretZero only for discovery, authoring, seeding, sync, and human entry (`web` / `agent sync --web`). All focused skills inherit this rule. +- **Agent skill guidance split:** SecretZero guidance is now split into focused skills — `skills/secretzero-author/SKILL.md` (schema-compliant Secretfile authoring, **guided session** with manifest-root confirmation, inventory table, add/edit loop with generator/target menus, optional `detect`/`discover`, optional background `secretzero web`, Hermes + MCP guidance, `.szvar` lane breakout, and policy-bound targets), `skills/secretzero-agent/SKILL.md` (agentic vectors, runtime/API workflows, and installation/onboarding), `skills/secretzero-handle/SKILL.md` (`SZ_AGENT_MODE`, `.env`/ingest preseed, spill-safe CLI), and `skills/secretzero-agent-adopt/SKILL.md` (Hermes/OpenClaw `agent list` / `agent adopt` bootstrap and restore loops). - **`secretzero agent list` / `agent adopt`:** Discover local Hermes/OpenClaw installs (read-only) and bootstrap SecretZero environments from **present** catalog credentials without emitting values. `agent adopt` writes `Secretfile.yml` into `--output-dir` (default: agent install path); `agent backup` is an alias. Supports `--template`, `--preseed-lockfile`, autodetect (Hermes then OpenClaw), and idempotent merge on re-adopt. See `docs/superpowers/specs/2026-05-27-agent-adopt-design.md`, `.mex/patterns/agent-adopt.md`. - **`secretzero agent instructions`:** Read-only Rich/JSON report of `agent_instructions` (summary + numbered steps). Default scope is pending manual secrets (same semantics as `agent sync`); `--all` lists every secret with instructions; `--detailed` adds optional metadata. See `.mex/patterns/agent-instructions-report.md`. - **Environment-map lanes + target profiles:** Secretfile now supports top-level `environments` and `target_profiles`; CLI (`sync`, `agent sync`, `web`) and API (`/sync`, `/agent/sync`) resolve lane-specific var files/lockfiles/profile defaults with runtime flags taking precedence. `secretzero web` now renders an environment dropdown and recomputes lane context on selection. @@ -67,6 +68,7 @@ Then read this file fully before doing anything else in this session. - **Ansible Vault extension:** existing `ansible_vault` provider now exposes target kind **`ansible_vault_file`** so encrypted vault files participate directly in target dispatch. - **Auto-generated provider bundle reference docs:** `scripts/generate_provider_bundle_docs.py` now emits `docs/reference/provider-bundles-auto.md` from the live `BundleRegistry`; wired into `task docs:build` / `task docs:serve` via `task docs:generate:provider-bundles`. - **FAQ clarification for encrypted-in-git lanes:** `docs/reference/faq.md` now explains that SOPS/git-crypt/Ansible Vault workflows are target-layer encrypted repository adapters; the true secret-zero trust anchor remains the bootstrap credential/key material used to unlock them. +- **Docs hyperlink gate:** `task docs:links` runs lychee on `README.md` and `docs/` (`lychee.toml`); wired into `scripts/agent.pre-commit.sh`, `.pre-commit-config.yaml`, and GitHub Actions (`test.yaml` job `docs-links`, `docs.yaml` pre-build). See `.mex/patterns/docs-links-lychee.md`. - **Public onboarding docs now front-load remote agent skill install paths:** `README.md` and `docs/index.md` both include an early **Agent Quick Start** with raw `SKILL.md` URLs, Hermes direct install commands, and a raw-download helper script (`scripts/download-secretzero-skills.zsh`) for copying both skill folders into `./skills` / `~/.agents/skills` / Hermes `external_dirs`. - **Structured secret hashing:** Lockfile hashing now accepts non-string secret payloads (e.g. JSON objects for multi-field static secrets) via canonical JSON normalization before SHA-256, preventing `'dict' object has no attribute 'encode'` during sync. - **Example manifest:** `examples/azure-appreg-to-aws-sm.yml` uses a structured static `value` map with YAML `null` leaves so interactive `secretzero sync` prompts once per missing field (sorted keys); `.szvar` / `--var-file` can pre-fill those leaves to skip prompts. diff --git a/.mex/context/setup.md b/.mex/context/setup.md index 6706874..bcccd14 100644 --- a/.mex/context/setup.md +++ b/.mex/context/setup.md @@ -52,7 +52,8 @@ last_updated: 2026-04-10 - `secretzero sync` — perform generation/sync and update lockfile. - `task lint:fix && task format && task schema:update` — local quality + schema maintenance. - `task test && task security:scan && task test:validations` — full verification pipeline. `task security:scan` syncs the frozen `--all-extras` environment before auditing dependencies/code. -- `task pre-commit` — install and run local pre-commit hooks; the repo hook now runs `task security:scan`. +- `task pre-commit` — install and run local pre-commit hooks; hooks run `task security:scan` and `task docs:links` (lychee on `README.md` + `docs/`). +- `task docs:links` — check hyperlinks in `README.md` and `docs/` (requires `lychee` via `mise install`). ## Common Issues **Unknown generator/target/provider kind:** ensure bundle registration path exists and provider extras are installed. diff --git a/.mex/patterns/INDEX.md b/.mex/patterns/INDEX.md index 7aa87d5..d1423f1 100644 --- a/.mex/patterns/INDEX.md +++ b/.mex/patterns/INDEX.md @@ -14,6 +14,7 @@ Lookup table for all pattern files in this directory. Check here before starting | [aws-json-target-format.md](aws-json-target-format.md) | Changing AWS `ssm_parameter` / `secrets_manager` structured JSON target behavior or docs | | [backup-cli-workflow.md](backup-cli-workflow.md) | Changing `secretzero backup create` / `backup restore` defaults, encryption mode, or environment fan-out | | [docs-entrypoint-parity.md](docs-entrypoint-parity.md) | Updating `README.md` and `docs/index.md` together for install/onboarding/agent-skill guidance | +| [docs-links-lychee.md](docs-links-lychee.md) | `task docs:links` / lychee config for README and `docs/` hyperlink checks | | [gitnexus-metagit-integration.md](gitnexus-metagit-integration.md) | GitNexus `secrets_overlay`, MetaGit registry, discovery bindings, blast-radius CLI | | [debug-sync.md](debug-sync.md) | Diagnosing sync failures across config/provider/generator/target boundaries | | [file-target-tfvars.md](file-target-tfvars.md) | Local `file` target `format: tfvars` for Terraform `.tfvars` assignment files | diff --git a/.mex/patterns/docs-links-lychee.md b/.mex/patterns/docs-links-lychee.md new file mode 100644 index 0000000..db6eeed --- /dev/null +++ b/.mex/patterns/docs-links-lychee.md @@ -0,0 +1,36 @@ +--- +name: docs-links-lychee +description: Validate hyperlinks in README.md and docs/ with lychee. +triggers: + - "broken link" + - "lychee" + - "docs:links" +last_updated: 2026-06-04 +--- + +# Docs hyperlink check (lychee) + +## Command + +```bash +task docs:links +``` + +Scans `README.md` and `docs/` using `lychee.toml` (loopback excluded, example URLs excluded). + +## When it runs + +- **CI:** `.github/workflows/test.yaml` job `docs-links` (every push/PR); `.github/workflows/docs.yaml` before MkDocs build on `main` +- End of agent work: `./scripts/agent.pre-commit.sh` (fast and full) +- Pre-commit hook: `secretzero-docs-links` in `.pre-commit-config.yaml` +- After editing docs or README + +## Fixing failures + +1. Prefer fixing the URL (404/410) or pointing to `https://secret0.com` / `https://github.com/zloeber/SecretZero/issues` instead of disabled GitHub Discussions. +2. For intentional non-checkable URLs (localhost docs, placeholders), add a regex to `lychee.toml` `exclude` — do not disable the task. +3. Install tool: `mise install` (see `mise.toml` `lychee` tool). + +## Example manifest links + +Jenkins CI example manifest: `examples/multi-cicd.yml` (not `jenkins-credentials.yml`). diff --git a/.mex/patterns/secretfile-authoring.md b/.mex/patterns/secretfile-authoring.md index 2d5626c..23947d8 100644 --- a/.mex/patterns/secretfile-authoring.md +++ b/.mex/patterns/secretfile-authoring.md @@ -13,7 +13,7 @@ edges: condition: when command usage or environment setup is needed - target: patterns/add-secret.md condition: when authoring includes adding/changing secret entries -last_updated: 2026-04-14 +last_updated: 2026-06-04 --- # Secretfile Authoring @@ -50,6 +50,8 @@ policies: glob: us-east-1 ``` +**Guided manifests (new or existing):** follow `skills/secretzero-author/SKILL.md` → **Guided authoring session** (manifest root → optional `detect`/`discover` → inventory table → add/edit loop with `secret-types` menus → validate → optional `secretzero web` on localhost). Hermes + MCP: use CLI/MCP tools for discovery, not sampling. + **Discovery-assisted authoring loop (agent-safe):** 1. Inspect current provider identity metadata with `secretzero status --format json`. 2. Capture stable actor fields (`account`, `region`, `arn`, `tenant_id`, etc.) for each provider alias. diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index bcf4a23..7837fd3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -7,3 +7,9 @@ repos: language: system pass_filenames: false always_run: true + - id: secretzero-docs-links + name: secretzero docs link check (lychee) + entry: zsh -lc 'task docs:links' + language: system + pass_filenames: false + files: ^(README\.md|docs/) diff --git a/AGENTS.md b/AGENTS.md index df98024..5679033 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,8 @@ SecretZero is a **schema-driven** secrets-as-code tool with multiple integrated ## Core Principles (Apply Across All Sub-Projects) - **Schema-driven development is mandatory**: All changes to configuration, validation, or behavior must flow through the Pydantic models in `src/secretzero/models.py` (or equivalent). Run `task schema:update` after any model changes to regenerate `Secretfile.schema.json` and keep CLI, API, skills, and examples in parity. -- **Zero-leakage rule**: Never request, receive, log, store, or allow plaintext secret values into any agent/LLM context, history, logs, or responses. +- **Absolute rule — SecretZero only, never secrets in context**: Agents must not consume secret values in LLM/tool context (no paste in chat, no reading `.env`/credential files into context, no `get --reveal` / `render` / value dumps). Use SecretZero end-to-end for discovery (metadata-only), authoring (placeholders), seeding (`agent sync --web`, `secretzero web`), sync, and audit. Canonical wording: `skills/secretzero/SKILL.md`. +- **Zero-leakage rule** (same mandate): Never request, receive, log, store, or allow plaintext secret values into any agent/LLM context, history, logs, or responses. - **Feature parity**: Ensure new features (especially agentic capabilities) are implemented consistently in the CLI (`secretzero` command), the FastAPI REST API, the skills system, and any related sub-projects (Terraform, docs, .mex patterns). - Prefer JSON output (`--json` for CLI, appropriate API endpoints) for machine-readable results. - After model/schema changes, always update: @@ -99,6 +100,8 @@ At the end of any coding work, run a fast local gate: ./scripts/agent.pre-commit.sh --mode fast --quiet ``` +The gate runs `task docs:links` (lychee hyperlink check on `README.md` and `docs/`). For doc-only edits: `task docs:links`. + Before any push/merge, run the full gate: ```bash diff --git a/README.md b/README.md index 6280aa3..33f07ab 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,6 @@ agent_targets: - skills/secretzero-agent/SKILL.md - skills/secretzero-handle/SKILL.md --> -[test](./AGENTS.md)
Secret0 logo diff --git a/Taskfile.yml b/Taskfile.yml index d1a62a3..882d3e8 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -167,6 +167,16 @@ tasks: cmds: - uv run python scripts/generate_provider_bundle_docs.py --output docs/reference/provider-bundles-auto.md + docs:links: + desc: Check hyperlinks in README.md and docs/ (lychee) + cmds: + - | + if ! command -v lychee >/dev/null 2>&1; then + echo "lychee not found. Install with: mise install (see mise.toml) or https://github.com/lycheeverse/lychee" + exit 1 + fi + lychee --config lychee.toml README.md docs/ + docker:build: desc: Build a Docker image from a Dockerfile vars: diff --git a/docs/examples/index.md b/docs/examples/index.md index 076479c..db44e19 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -37,7 +37,7 @@ Access the complete collection of example Secretfiles in the GitHub repository w | **Multi-Cloud** | Hybrid / multi-provider cloud | multi-cloud.yml | | **Kubernetes** | Container orchestration | kubernetes-*.yml | | **CI/CD Pipelines** | Automated workflows | github-actions.yml, gitlab-cicd.yml | -| **Jenkins** | Legacy CI/CD | jenkins-credentials.yml | +| **Jenkins** | Legacy CI/CD | multi-cicd.yml | ### By Complexity diff --git a/docs/examples/jenkins-credentials.md b/docs/examples/jenkins-credentials.md index e401995..ff0ef1f 100644 --- a/docs/examples/jenkins-credentials.md +++ b/docs/examples/jenkins-credentials.md @@ -6,12 +6,12 @@ This page highlights the Jenkins credentials example used in documentation. The canonical example lives in the repository: -- https://github.com/zloeber/SecretZero/blob/main/examples/jenkins-credentials.yml +- https://github.com/zloeber/SecretZero/blob/main/examples/multi-cicd.yml ## Usage ```bash -curl -O https://raw.githubusercontent.com/zloeber/SecretZero/main/examples/jenkins-credentials.yml -mv jenkins-credentials.yml Secretfile.yml +curl -O https://raw.githubusercontent.com/zloeber/SecretZero/main/examples/multi-cicd.yml +cp multi-cicd.yml Secretfile.yml secretzero sync ``` diff --git a/docs/examples/repository.md b/docs/examples/repository.md index b35408a..6b25f8f 100644 --- a/docs/examples/repository.md +++ b/docs/examples/repository.md @@ -346,20 +346,19 @@ git push --- -#### jenkins-credentials.yml +#### multi-cicd.yml -**Purpose**: Jenkins integration +**Purpose**: Multi-provider CI/CD integration (GitHub, GitLab, Jenkins) **Features**: -- Jenkins credential store -- Pipeline integration -- Jenkinsfile examples -- Credential rotation +- Jenkins credential store targets +- GitHub and GitLab secret targets +- Shared secrets across CI systems **Usage**: ```bash -curl -O https://raw.githubusercontent.com/zloeber/SecretZero/main/examples/jenkins-credentials.yml -mv jenkins-credentials.yml Secretfile.yml +curl -O https://raw.githubusercontent.com/zloeber/SecretZero/main/examples/multi-cicd.yml +cp multi-cicd.yml Secretfile.yml secretzero sync ``` @@ -683,7 +682,7 @@ metadata: ### Community - **GitHub Issues**: [Report issues or ask questions](https://github.com/zloeber/SecretZero/issues) -- **Discussions**: [Community discussions](https://github.com/zloeber/SecretZero/discussions) +- **Discussions**: [Community discussions](https://github.com/zloeber/SecretZero/issues) - **README**: [Main README](https://github.com/zloeber/SecretZero/blob/main/README.md) ### Example-Specific Help diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index d6bae94..3f22ba4 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -181,7 +181,7 @@ If you run into issues: - Check the [FAQ](../reference/faq.md) for common questions - Review the [Troubleshooting Guide](../reference/troubleshooting.md) - Search [existing issues](https://github.com/zloeber/SecretZero/issues) -- Ask in [GitHub Discussions](https://github.com/zloeber/SecretZero/discussions) +- Ask in [GitHub Discussions](https://github.com/zloeber/SecretZero/issues) - Open a [new issue](https://github.com/zloeber/SecretZero/issues/new) Let's get started! 🚀 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index eee745f..3f1ca9a 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -435,4 +435,4 @@ If you encounter installation issues: - Check the [Troubleshooting Guide](../reference/troubleshooting.md) - Search [GitHub Issues](https://github.com/zloeber/SecretZero/issues) -- Ask in [GitHub Discussions](https://github.com/zloeber/SecretZero/discussions) +- Ask in [GitHub Discussions](https://github.com/zloeber/SecretZero/issues) diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 5a594ea..db1a412 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -453,4 +453,4 @@ Need assistance? - [FAQ](../reference/faq.md) - Common questions - [Troubleshooting](../reference/troubleshooting.md) - Solutions to common issues - [GitHub Issues](https://github.com/zloeber/SecretZero/issues) - Report bugs -- [Discussions](https://github.com/zloeber/SecretZero/discussions) - Ask questions +- [Discussions](https://github.com/zloeber/SecretZero/issues) - Ask questions diff --git a/docs/index.md b/docs/index.md index 80d4c0e..5b4a43c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -452,7 +452,7 @@ graph TB - **GitHub**: [zloeber/SecretZero](https://github.com/zloeber/SecretZero) - **Issues**: [Report bugs or request features](https://github.com/zloeber/SecretZero/issues) -- **Discussions**: [Ask questions and share ideas](https://github.com/zloeber/SecretZero/discussions) +- **Discussions**: [Ask questions and share ideas](https://github.com/zloeber/SecretZero/issues) ## License diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index 64f0842..5c1d916 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -194,7 +194,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 #### Examples & Documentation - `github-actions.yml` - GitHub Actions integration guide - `gitlab-cicd.yml` - GitLab CI/CD integration guide -- `jenkins-credentials.yml` - Jenkins integration guide +- `multi-cicd.yml` - Multi-provider CI/CD example (includes Jenkins) - `multi-cicd.yml` - Multi-platform integration ### Testing diff --git a/docs/reference/faq.md b/docs/reference/faq.md index 281a23e..3124678 100644 --- a/docs/reference/faq.md +++ b/docs/reference/faq.md @@ -980,9 +980,9 @@ secretzero sync ### Where can I get support? -- **Documentation**: [secretzero.readthedocs.io](https://secretzero.readthedocs.io) +- **Documentation**: [secret0.com](https://secret0.com) - **GitHub Issues**: [Report bugs](https://github.com/zloeber/SecretZero/issues) -- **Discussions**: [Ask questions](https://github.com/zloeber/SecretZero/discussions) +- **Discussions**: [Ask questions](https://github.com/zloeber/SecretZero/issues) - **Examples**: [View examples](../examples/index.md) ### How do I report a bug? diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 375e9df..82142be 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -1209,7 +1209,7 @@ If none of these solutions work, please [open an issue](https://github.com/zloeb - [FAQ](faq.md) - Common questions - [Architecture](architecture.md) - Technical details -- [GitHub Discussions](https://github.com/zloeber/SecretZero/discussions) - Community support +- [GitHub Discussions](https://github.com/zloeber/SecretZero/issues) - Community support - [Examples](../examples/index.md) - Working configurations ## See Also diff --git a/docs/user-guide/configuration/validation.md b/docs/user-guide/configuration/validation.md index 34e2d68..b492251 100644 --- a/docs/user-guide/configuration/validation.md +++ b/docs/user-guide/configuration/validation.md @@ -823,7 +823,7 @@ If validation fails and you can't determine why: 1. Check [Troubleshooting Guide](../../reference/troubleshooting.md) 2. Review [Examples](../../examples/index.md) for reference 3. Search [GitHub Issues](https://github.com/zloeber/SecretZero/issues) -4. Ask in [Discussions](https://github.com/zloeber/SecretZero/discussions) +4. Ask in [Discussions](https://github.com/zloeber/SecretZero/issues) ## Next Steps diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 8a15362..fea9c9f 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -274,7 +274,7 @@ secrets: - **GitHub**: [zloeber/SecretZero](https://github.com/zloeber/SecretZero) - **Issues**: [Report bugs or request features](https://github.com/zloeber/SecretZero/issues) -- **Discussions**: [Ask questions and share ideas](https://github.com/zloeber/SecretZero/discussions) +- **Discussions**: [Ask questions and share ideas](https://github.com/zloeber/SecretZero/issues) ## Next Steps diff --git a/docs/user-guide/providers/azure.md b/docs/user-guide/providers/azure.md index d1892e3..63f4a5f 100644 --- a/docs/user-guide/providers/azure.md +++ b/docs/user-guide/providers/azure.md @@ -166,7 +166,7 @@ Azure Key Vault provides secure storage for secrets, keys, and certificates with | Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| -| `vault_url` | string | Yes | - | Key Vault URL (e.g., https://myvault.vault.azure.net) | +| `vault_url` | string | Yes | - | Key Vault URL (e.g., `https://{vault-name}.vault.azure.net`) | | `secret_name` | string | Yes | - | Name of the secret in Key Vault | | `content_type` | string | No | - | Content type metadata (e.g., "application/json") | | `tags` | object | No | - | Key-value tags for the secret | diff --git a/docs/user-guide/providers/jenkins.md b/docs/user-guide/providers/jenkins.md index 2f758c8..8a92b31 100644 --- a/docs/user-guide/providers/jenkins.md +++ b/docs/user-guide/providers/jenkins.md @@ -1298,6 +1298,6 @@ Jenkins API tokens have the same permissions as the user who created them: ### Related Tools -- [python-jenkins](https://github.com/pycontribs/python-jenkins) - Python library for Jenkins API +- [python-jenkins](https://opendev.org/jjb/python-jenkins) - Python library for Jenkins API - [jenkins-job-builder](https://docs.openstack.org/infra/jenkins-job-builder/) - Jenkins job configuration - [jenkins-cli](https://www.jenkins.io/doc/book/managing/cli/) - Jenkins command-line interface diff --git a/docs/user-guide/targets/jenkins.md b/docs/user-guide/targets/jenkins.md index 58fa126..132210a 100644 --- a/docs/user-guide/targets/jenkins.md +++ b/docs/user-guide/targets/jenkins.md @@ -1323,4 +1323,4 @@ Jenkins credentials targets in SecretZero provide: - ✅ Jenkins-managed credential encryption at rest - ✅ Multi-Jenkins instance support -For additional help or examples, refer to the [examples directory](../../examples/index.md) or [open an issue](https://github.com/yourusername/secretzero/issues). +For additional help or examples, refer to the [examples directory](../../examples/index.md) or [open an issue](https://github.com/zloeber/SecretZero/issues). diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..6ec8a33 --- /dev/null +++ b/lychee.toml @@ -0,0 +1,17 @@ +# Link checker for README.md and docs/. Run: task docs:links + +verbose = "warn" +no_progress = true +max_redirects = 10 +timeout = 25 +exclude_loopback = true +include_mail = false + +# Bot-blocked or example-only URLs (not doc defects) +exclude = [ + '^https://myvault\.vault\.azure\.net', + '^https://jenkins\.example\.com', + '^https://github\.com/yourusername/', + '^https://gitlab\.com/-/profile/personal_access_tokens', + '^https://www\.hhs\.gov/hipaa', +] diff --git a/mise.toml b/mise.toml index efd9caa..124703c 100644 --- a/mise.toml +++ b/mise.toml @@ -11,6 +11,7 @@ yq = "latest" npm = "latest" node = "22.22" gh = "latest" +lychee = "latest" [tools."github:asciinema/agg"] version = "latest" diff --git a/scripts/agent.pre-commit.sh b/scripts/agent.pre-commit.sh index 7e8e775..05aa098 100755 --- a/scripts/agent.pre-commit.sh +++ b/scripts/agent.pre-commit.sh @@ -128,6 +128,9 @@ fi wait "${pid_security}" wait "${pid_valid}" +log "==> Checking README and docs hyperlinks (lychee)" +task docs:links + git status --porcelain | awk '{print substr($0,4)}' | sort -u > "${tmp_after}" comm -13 "${tmp_before}" "${tmp_after}" > "${tmp_new}" @@ -141,6 +144,7 @@ if [[ -s "${tmp_new}" ]]; then echo " 2) Re-run at least:" echo " task test" echo " task security:scan" + echo " task docs:links" exit 2 fi diff --git a/skills/secretzero-agent-adopt/SKILL.md b/skills/secretzero-agent-adopt/SKILL.md index f5a0563..b94fab3 100644 --- a/skills/secretzero-agent-adopt/SKILL.md +++ b/skills/secretzero-agent-adopt/SKILL.md @@ -3,7 +3,8 @@ name: secretzero-agent-adopt description: | Use for agent runtime integration: discover Hermes/OpenClaw installs, bootstrap SecretZero environments with `secretzero agent list` / `agent adopt`, - lockfile preseed, and restore loops. Never emit secret values into agent context. + lockfile preseed, and restore loops. Inherits absolute rule from + `skills/secretzero/SKILL.md` (SecretZero only; never secrets in context). --- # SecretZero Agent Adopt Skill diff --git a/skills/secretzero-agent/SKILL.md b/skills/secretzero-agent/SKILL.md index 61e1de9..bc06a27 100644 --- a/skills/secretzero-agent/SKILL.md +++ b/skills/secretzero-agent/SKILL.md @@ -41,7 +41,7 @@ secretzero agent sync --help ## Core Agent Contract -- Never request, receive, or print plaintext secret values. +**Absolute rule:** `skills/secretzero/SKILL.md` — never consume secrets in context; use SecretZero for all handling (`agent sync`, `--web`, validate, status). Never request, receive, or print plaintext secret values. - Prefer JSON output for machine handling. - When running in automation or spill-sensitive hosts, set **`SZ_AGENT_MODE=true`** so the CLI blocks or redacts commands that would dump secret-bearing config (see `skills/secretzero-handle/SKILL.md`). - Use the unified entrypoint: diff --git a/skills/secretzero-author/SKILL.md b/skills/secretzero-author/SKILL.md index 8eeb5e8..4bd0aac 100644 --- a/skills/secretzero-author/SKILL.md +++ b/skills/secretzero-author/SKILL.md @@ -1,33 +1,231 @@ --- name: secretzero-author description: | - Use when authoring, reviewing, or discovering `Secretfile.yml` manifests. - Focuses on schema-compliant manifest quality, safe contextless discovery, - environment-aware `.szvar` separation, and policy-bound provider targets. - When work touches `.env`, local `file` targets, or spill-safe agent CLI, - also load `skills/secretzero-handle/SKILL.md`. + 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 secret discovery safe and contextless (no secret values requested or echoed). +- 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. ## Safety Rules (Non-Negotiable) -- Never ask for, copy, log, or output plaintext secret values. -- Discovery must use metadata only (`status`, `test`, provider identity fields), not secret retrieval. -- Do not run `secretzero get --reveal` in agent sessions. +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: + +| Concept | Meaning | +|---------|---------| +| **Manifest root** | Directory that will contain `Secretfile.yml` (and usually `.gitsecrets.lock`) | +| **CLI path** | `secretzero -f /Secretfile.yml …` for all later commands | + +**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) + +| User choice | When it makes sense | Command (agent-safe; no values in output) | +|-------------|---------------------|-------------------------------------------| +| **Light scan** | `.env`, `.env.*`, `secrets*`, `credentials*` files may exist | `secretzero detect --all-keys --format json` | +| **Deep scan** | Many config files; want ranked candidates + `Secretfile.detect.yml` draft | `secretzero discover --local-only --dry-run --format json` (add `--no-llm` if LLM must stay off) | +| **Skip** | Greenfield or user already has a secret list | Continue to Phase 2 (inventory) or Phase 3 (add loop) | + +**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):** + +```bash +secretzero list secrets -f /Secretfile.yml --format json +secretzero status -f /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): + +| Secret | Generator | Targets | Lockfile status | +|--------|-----------|---------|-----------------| +| `db_password` | `random_password` | `local/file`, `aws/ssm_parameter` | synced | +| `api_key` | `static` | `local/file` | not_synced | + +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): + + ```bash + secretzero secret-types + secretzero secret-types --type --verbose + secretzero list providers -f /Secretfile.yml --format json + secretzero list targets -f /Secretfile.yml --format json + ``` + +3. **Generator menu** (`secrets[].kind`) — present as lettered options: + + | 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 PAT via API | + | G | `entra-agent-blueprint` | Agent Identity blueprint lifecycle | + | H | `provider_backed` | Advanced; only if no bundle-specific kind fits | + +4. **Target menu** — from `list targets` + **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 /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): + +```bash +cd +secretzero web -f Secretfile.yml --host 127.0.0.1 --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. + +| Phase | Hermes chat | SecretZero via MCP / CLI | +|-------|-------------|---------------------------| +| 0 Manifest root | Always ask in chat | — | +| 1 Discovery | Offer yes/no | Tools should wrap `detect` or `discover --local-only --dry-run --format json` | +| 2 Inventory | Format JSON as markdown table | `list secrets` / `status --format json` | +| 3 Add/edit loop | Menus + user choices | `secret-types`, `list providers`, `list targets`; write YAML via edit tool | +| 4 Validate | Report errors | `validate`, `sync --dry-run` (API: `POST /config/validate` where exposed) | +| 5 Web / seed | Offer dashboard; hand off sync skill | `web` subprocess or `agent sync` tool | + +**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: @@ -58,6 +256,7 @@ Verify: ```bash secretzero --help secretzero validate --help +secretzero secret-types secretzero list providers secretzero list targets ``` @@ -158,22 +357,26 @@ Attach `identity_policies` on cloud targets when sync must be lane-bound (see be ## 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. **Use the decision map** +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. -3. **Model whole secrets first** +4. **Model whole secrets first** - One logical secret per `secrets[]` entry unless a true multi-field bundle is needed. -4. **Select generator intentionally** +5. **Select generator intentionally** - Prefer `random_password`, `random_string`, `static` (or static-like kinds) before `script` / `provider_backed`. -5. **Map explicit targets** +6. **Map explicit targets** - Every secret has clear targets unless intentionally deferred (e.g. Entra blueprint metadata-only phase). -6. **Break out environment variance** +7. **Break out environment variance** - Keep structural defaults in `Secretfile.yml`. - Move lane-specific values to `*.szvar` files (`dev.szvar`, `staging.szvar`, `prod.szvar`). -7. **Apply identity guardrails** +8. **Apply identity guardrails** - Add `kind: provider_identity` policies and attach with `identity_policies` where needed. -8. **Validate in loop** +9. **Validate in loop** - `secretzero validate` - `secretzero render` (if interpolation/templating is used) - `secretzero sync --dry-run --var-file .szvar` @@ -218,17 +421,25 @@ aws_region: us-west-2 ## Contextless Secret Discovery (Safe Mode) -Use only discovery commands that return metadata: +Use only discovery commands that return metadata (no secret values): ```bash +# Local repo scan (names / paths only) +secretzero detect --all-keys --format json +secretzero discover --local-only --dry-run --format json + +# Provider / lockfile metadata (existing manifest) secretzero status --format json secretzero test --verbose --format json secretzero list providers secretzero list targets +secretzero secret-types ``` 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. @@ -263,6 +474,7 @@ policies: ## 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. diff --git a/skills/secretzero-handle/SKILL.md b/skills/secretzero-handle/SKILL.md index 742df25..f202936 100644 --- a/skills/secretzero-handle/SKILL.md +++ b/skills/secretzero-handle/SKILL.md @@ -9,6 +9,8 @@ description: | # SecretZero Handle (spill-safe context) +Enforces **`skills/secretzero/SKILL.md` absolute rule**: SecretZero only for secrets; never load values into agent context. + Use this skill **together with** `skills/secretzero-agent/SKILL.md` and `skills/secretzero-author/SKILL.md` whenever: - The manifest references **`.env`**, `*.env`, or **`local` / `file`** targets that read or write environment files. diff --git a/skills/secretzero/SKILL.md b/skills/secretzero/SKILL.md index fbb882a..189f061 100644 --- a/skills/secretzero/SKILL.md +++ b/skills/secretzero/SKILL.md @@ -1,9 +1,10 @@ --- name: secretzero description: | - Compatibility entrypoint for SecretZero skills. Route to the focused skills: - secretzero-author (manifest authoring/discovery) and secretzero-agent - (agentic/runtime workflows). + Compatibility entrypoint for SecretZero skills. Enforces the absolute rule: + never consume secrets in agent context — use SecretZero for all secret + handling. Routes to secretzero-author, secretzero-agent, secretzero-handle, + and secretzero-agent-adopt. --- # SecretZero Skill Router @@ -11,9 +12,25 @@ description: | This skill is retained for backwards compatibility and publishing stability. Use one of the focused skills below for all new work. +## Absolute rule: SecretZero only — never secrets in context + +**Agents must never consume secret values in LLM or tool context.** That includes reading, receiving, pasting, transcribing, “debugging with,” summarizing, or inferring plaintext from files the user shares in chat. + +**Use SecretZero entirely for secrets handling** — discovery, authoring, validation, seeding, sync, rotate, drift, and human entry. The agent orchestrates **metadata-only** CLI/API/MCP results; SecretZero and approved human surfaces hold the values. + +| Forbidden | Use instead | +|-----------|-------------| +| User pastes API keys/passwords into chat | `secretzero agent sync --web`, `secretzero web`, or Vector 1 instructions | +| `read_file` / grep / cat on `.env`, `.env.*`, `*.pem`, credential files | `secretzero detect`, `discover`, `ingest preseed` (metadata / hashes only) | +| `secretzero get --reveal`, `render`, `backup restore --print` under agents | `agent sync --json`, `status`, `list secrets`, lockfile hashes | +| MCP sampling or host-LLM scans over secret file contents | `detect` / `discover` tools (names, paths, confidence — no values) | +| Putting literals in `Secretfile.yml` during agent authoring | `null`, `${VAR}`, `.szvar`; `SZ_AGENT_MODE=true` + `secretzero-handle` | + +On spill-sensitive hosts set **`SZ_AGENT_MODE=true`** (see `skills/secretzero-handle/SKILL.md`). All focused skills below inherit this rule. + ## Use `secretzero-author` when -- Creating or editing `Secretfile.yml`. +- Creating or editing `Secretfile.yml` (guided: manifest root, inventory table, add/edit loop, optional `detect`/`discover`, optional `secretzero web`; Hermes + MCP notes in skill). - Performing schema-first, high-quality manifest authoring. - Doing safe, contextless discovery and `.szvar` environment breakout. - Adding least-privilege provider identity policy binding for targets. From e5209c232414be9ed240f95d8eec3b1c9c8540d3 Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Thu, 4 Jun 2026 17:13:00 -0500 Subject: [PATCH 02/10] fix(ci): use correct lychee GitHub release tag for install Release assets are published under lychee-vX.Y.Z, not vX.Y.Z, which caused 404s when downloading the Linux tarball in test and docs workflows. --- .github/workflows/docs.yaml | 4 ++-- .github/workflows/test.yaml | 5 +++-- .mex/patterns/docs-links-lychee.md | 1 + lychee.toml | 1 + 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index ffdf4b8..ccae197 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -33,10 +33,10 @@ jobs: - name: Install lychee env: - LYCHEE_VERSION: v0.24.2 + LYCHEE_TAG: lychee-v0.24.2 run: | curl -fsSL \ - "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_VERSION}/lychee-x86_64-unknown-linux-gnu.tar.gz" \ + "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_TAG}/lychee-x86_64-unknown-linux-gnu.tar.gz" \ | tar xz install -m 755 lychee /usr/local/bin/lychee diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 997a946..6c4c3ec 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -22,10 +22,11 @@ jobs: - name: Install lychee env: - LYCHEE_VERSION: v0.24.2 + # Release tags use the lychee-vX.Y.Z prefix (not bare vX.Y.Z). + LYCHEE_TAG: lychee-v0.24.2 run: | curl -fsSL \ - "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_VERSION}/lychee-x86_64-unknown-linux-gnu.tar.gz" \ + "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_TAG}/lychee-x86_64-unknown-linux-gnu.tar.gz" \ | tar xz install -m 755 lychee /usr/local/bin/lychee lychee --version diff --git a/.mex/patterns/docs-links-lychee.md b/.mex/patterns/docs-links-lychee.md index db6eeed..d36b7e0 100644 --- a/.mex/patterns/docs-links-lychee.md +++ b/.mex/patterns/docs-links-lychee.md @@ -30,6 +30,7 @@ Scans `README.md` and `docs/` using `lychee.toml` (loopback excluded, example UR 1. Prefer fixing the URL (404/410) or pointing to `https://secret0.com` / `https://github.com/zloeber/SecretZero/issues` instead of disabled GitHub Discussions. 2. For intentional non-checkable URLs (localhost docs, placeholders), add a regex to `lychee.toml` `exclude` — do not disable the task. 3. Install tool: `mise install` (see `mise.toml` `lychee` tool). +4. CI pins GitHub release tag `lychee-vX.Y.Z` (not bare `vX.Y.Z`) in `.github/workflows/test.yaml` and `docs.yaml`. ## Example manifest links diff --git a/lychee.toml b/lychee.toml index 6ec8a33..b0f94b4 100644 --- a/lychee.toml +++ b/lychee.toml @@ -1,4 +1,5 @@ # Link checker for README.md and docs/. Run: task docs:links +# CI installs lychee from GitHub release tag lychee-v0.24.2 (see test.yaml / docs.yaml). verbose = "warn" no_progress = true From 4ee85f45d20403eed0fd6ea98af4131bf2828097 Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Thu, 4 Jun 2026 17:14:11 -0500 Subject: [PATCH 03/10] fix(security): bump pyjwt to >=2.13.0 for pip-audit CVE fixes Resolves PYSEC-2026-175/177/178/179 reported against pyjwt 2.12.1 in task security:scan / CI. --- pyproject.toml | 4 ++-- uv.lock | 9 +++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 6482b62..e3161b8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,7 +41,7 @@ CI = "https://github.com/zloeber/SecretZero/actions" [tool.uv] exclude-newer = "7 days" # CVE-2026-4539: pygments fix is often newer than the exclude-newer window. -exclude-newer-package = { anthropic = false, cryptography = false, idna = false, langchain-core = false, langchain-openai = false, langsmith = false, lxml = false, ollama = false, pip = false, pygments = false, pymdown-extensions = false, pytest = false, python-multipart = false, starlette = false, urllib3 = false } +exclude-newer-package = { anthropic = false, cryptography = false, idna = false, langchain-core = false, langchain-openai = false, langsmith = false, lxml = false, ollama = false, pip = false, pygments = false, pyjwt = false, pymdown-extensions = false, pytest = false, python-multipart = false, starlette = false, urllib3 = false } # Pin transitive minimums when pip-audit fix releases are newer than exclude-newer allows. override-dependencies = [ "anthropic>=0.87.0", @@ -55,7 +55,7 @@ override-dependencies = [ "lxml>=6.1.0", "ollama>=0.6.2", "pip>=26.0.2", - "pyjwt>=2.12.0", + "pyjwt>=2.13.0", "pymdown-extensions>=10.21.3", "pytest>=9.0.3", "python-multipart>=0.0.27", diff --git a/uv.lock b/uv.lock index 54788d9..be1e0ef 100644 --- a/uv.lock +++ b/uv.lock @@ -12,6 +12,7 @@ ollama = false langchain-core = false lxml = false urllib3 = false +pyjwt = false starlette = false cryptography = false langchain-openai = false @@ -36,7 +37,7 @@ overrides = [ { name = "lxml", specifier = ">=6.1.0" }, { name = "ollama", specifier = ">=0.6.2" }, { name = "pip", specifier = ">=26.0.2" }, - { name = "pyjwt", specifier = ">=2.12.0" }, + { name = "pyjwt", specifier = ">=2.13.0" }, { name = "pymdown-extensions", specifier = ">=10.21.3" }, { name = "pytest", specifier = ">=9.0.3" }, { name = "python-multipart", specifier = ">=0.0.27" }, @@ -2593,11 +2594,11 @@ wheels = [ [[package]] name = "pyjwt" -version = "2.12.1" +version = "2.13.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/c2/27/a3b6e5bf6ff856d2509292e95c8f57f0df7017cf5394921fc4e4ef40308a/pyjwt-2.12.1.tar.gz", hash = "sha256:c74a7a2adf861c04d002db713dd85f84beb242228e671280bf709d765b03672b", size = 102564, upload-time = "2026-03-13T19:27:37.25Z" } +sdist = { url = "https://files.pythonhosted.org/packages/3b/81/58d0ac84e1ef3a3843791d6954d94c0b33d526c75eeb1efbce9d0a4c4077/pyjwt-2.13.0.tar.gz", hash = "sha256:41571c89ca91598c79e8ef18a2d07367d4810fbbd6f637794879baf1b7703423", size = 107515, upload-time = "2026-05-21T19:54:36.618Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/e5/7a/8dd906bd22e79e47397a61742927f6747fe93242ef86645ee9092e610244/pyjwt-2.12.1-py3-none-any.whl", hash = "sha256:28ca37c070cad8ba8cd9790cd940535d40274d22f80ab87f3ac6a713e6e8454c", size = 29726, upload-time = "2026-03-13T19:27:35.677Z" }, + { url = "https://files.pythonhosted.org/packages/a3/5e/ecf12fdb62546d64385c158514e9b2b671f7832108ef2ecd2020ce0af2d1/pyjwt-2.13.0-py3-none-any.whl", hash = "sha256:66adcc2aff09b3f1bbd95fc1e1577df8ac8723c978552fd43304c8a290ac5728", size = 31274, upload-time = "2026-05-21T19:54:35.362Z" }, ] [[package]] From 648eca1d67ff6b8ab2bb4f311937e8a0526da9aa Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Thu, 4 Jun 2026 17:23:41 -0500 Subject: [PATCH 04/10] fix(ci): install lychee via lychee-action instead of curl tarball Manual release downloads can 404 on GitHub Actions runners (rate limits / redirect quirks). Use pinned lycheeverse/lychee-action@v2.8.0 with lycheeVersion v0.24.2 and GITHUB_TOKEN for reliable installs. --- .github/workflows/docs.yaml | 17 +++++++---------- .github/workflows/test.yaml | 19 +++++++------------ .mex/patterns/docs-links-lychee.md | 2 +- lychee.toml | 2 +- 4 files changed, 16 insertions(+), 24 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index ccae197..07743e7 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -31,17 +31,14 @@ jobs: run: | uv sync --frozen --all-extras - - name: Install lychee - env: - LYCHEE_TAG: lychee-v0.24.2 - run: | - curl -fsSL \ - "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_TAG}/lychee-x86_64-unknown-linux-gnu.tar.gz" \ - | tar xz - install -m 755 lychee /usr/local/bin/lychee - - name: Check README.md and docs/ hyperlinks - run: lychee --config lychee.toml README.md docs/ + uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0 + with: + args: --config lychee.toml README.md docs/ + fail: true + lycheeVersion: v0.24.2 + env: + GITHUB_TOKEN: ${{ github.token }} - name: Export Secretfile schema for docs run: | diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 6c4c3ec..b79a0b9 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -20,19 +20,14 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Install lychee - env: - # Release tags use the lychee-vX.Y.Z prefix (not bare vX.Y.Z). - LYCHEE_TAG: lychee-v0.24.2 - run: | - curl -fsSL \ - "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_TAG}/lychee-x86_64-unknown-linux-gnu.tar.gz" \ - | tar xz - install -m 755 lychee /usr/local/bin/lychee - lychee --version - - name: Check README.md and docs/ - run: lychee --config lychee.toml README.md docs/ + uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0 + with: + args: --config lychee.toml README.md docs/ + fail: true + lycheeVersion: v0.24.2 + env: + GITHUB_TOKEN: ${{ github.token }} schema-doc-parity: name: Schema/Docs Parity diff --git a/.mex/patterns/docs-links-lychee.md b/.mex/patterns/docs-links-lychee.md index d36b7e0..c60dfef 100644 --- a/.mex/patterns/docs-links-lychee.md +++ b/.mex/patterns/docs-links-lychee.md @@ -30,7 +30,7 @@ Scans `README.md` and `docs/` using `lychee.toml` (loopback excluded, example UR 1. Prefer fixing the URL (404/410) or pointing to `https://secret0.com` / `https://github.com/zloeber/SecretZero/issues` instead of disabled GitHub Discussions. 2. For intentional non-checkable URLs (localhost docs, placeholders), add a regex to `lychee.toml` `exclude` — do not disable the task. 3. Install tool: `mise install` (see `mise.toml` `lychee` tool). -4. CI pins GitHub release tag `lychee-vX.Y.Z` (not bare `vX.Y.Z`) in `.github/workflows/test.yaml` and `docs.yaml`. +4. CI uses `lycheeverse/lychee-action` (pinned SHA) with `lycheeVersion: v0.24.2` — do not hand-curl release tarballs (unreliable 404/rate limits on runners). ## Example manifest links diff --git a/lychee.toml b/lychee.toml index b0f94b4..b3c2040 100644 --- a/lychee.toml +++ b/lychee.toml @@ -1,5 +1,5 @@ # Link checker for README.md and docs/. Run: task docs:links -# CI installs lychee from GitHub release tag lychee-v0.24.2 (see test.yaml / docs.yaml). +# CI: lycheeverse/lychee-action with lycheeVersion v0.24.2 (see test.yaml / docs.yaml). verbose = "warn" no_progress = true From 3e3f2cd6423f6217a0520ce5e77f8f4fffd3f94e Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Thu, 4 Jun 2026 17:25:35 -0500 Subject: [PATCH 05/10] fix(ci): install lychee from nested v0.24.2 release layout lychee-action assumes the binary is at the tarball root; v0.24.2 ships lychee-x86_64-unknown-linux-gnu/lychee. Add scripts/ci-install-lychee.sh and call it from test/docs workflows instead of lychee-action. --- .github/workflows/docs.yaml | 11 ++++----- .github/workflows/test.yaml | 11 ++++----- .mex/patterns/docs-links-lychee.md | 2 +- lychee.toml | 2 +- scripts/ci-install-lychee.sh | 37 ++++++++++++++++++++++++++++++ 5 files changed, 47 insertions(+), 16 deletions(-) create mode 100755 scripts/ci-install-lychee.sh diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 07743e7..ee5e3fe 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -31,14 +31,11 @@ jobs: run: | uv sync --frozen --all-extras + - name: Install lychee + run: bash ./scripts/ci-install-lychee.sh + - name: Check README.md and docs/ hyperlinks - uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0 - with: - args: --config lychee.toml README.md docs/ - fail: true - lycheeVersion: v0.24.2 - env: - GITHUB_TOKEN: ${{ github.token }} + run: lychee --config lychee.toml README.md docs/ - name: Export Secretfile schema for docs run: | diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index b79a0b9..48266a7 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -20,14 +20,11 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Install lychee + run: bash ./scripts/ci-install-lychee.sh + - name: Check README.md and docs/ - uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0 - with: - args: --config lychee.toml README.md docs/ - fail: true - lycheeVersion: v0.24.2 - env: - GITHUB_TOKEN: ${{ github.token }} + run: lychee --config lychee.toml README.md docs/ schema-doc-parity: name: Schema/Docs Parity diff --git a/.mex/patterns/docs-links-lychee.md b/.mex/patterns/docs-links-lychee.md index c60dfef..aed3431 100644 --- a/.mex/patterns/docs-links-lychee.md +++ b/.mex/patterns/docs-links-lychee.md @@ -30,7 +30,7 @@ Scans `README.md` and `docs/` using `lychee.toml` (loopback excluded, example UR 1. Prefer fixing the URL (404/410) or pointing to `https://secret0.com` / `https://github.com/zloeber/SecretZero/issues` instead of disabled GitHub Discussions. 2. For intentional non-checkable URLs (localhost docs, placeholders), add a regex to `lychee.toml` `exclude` — do not disable the task. 3. Install tool: `mise install` (see `mise.toml` `lychee` tool). -4. CI uses `lycheeverse/lychee-action` (pinned SHA) with `lycheeVersion: v0.24.2` — do not hand-curl release tarballs (unreliable 404/rate limits on runners). +4. CI installs via `scripts/ci-install-lychee.sh` (handles v0.24+ nested release tarballs; `lychee-action` v2.8.0 still expects a flat `lychee` binary). ## Example manifest links diff --git a/lychee.toml b/lychee.toml index b3c2040..d183af4 100644 --- a/lychee.toml +++ b/lychee.toml @@ -1,5 +1,5 @@ # Link checker for README.md and docs/. Run: task docs:links -# CI: lycheeverse/lychee-action with lycheeVersion v0.24.2 (see test.yaml / docs.yaml). +# CI: scripts/ci-install-lychee.sh (see test.yaml / docs.yaml). verbose = "warn" no_progress = true diff --git a/scripts/ci-install-lychee.sh b/scripts/ci-install-lychee.sh new file mode 100755 index 0000000..36f9daa --- /dev/null +++ b/scripts/ci-install-lychee.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# Install lychee for GitHub Actions ubuntu runners (linux-gnu tarballs only). +# v0.24+ release tarballs nest the binary under lychee--unknown-linux-gnu/; +# older releases place `lychee` at the archive root. Local macOS dev: use `mise install`. +set -euo pipefail + +LYCHEE_TAG="${LYCHEE_TAG:-lychee-v0.24.2}" +ARCH="$(uname -m)" +ARCHIVE="lychee-${ARCH}-unknown-linux-gnu.tar.gz" +TEMP_DIR="${RUNNER_TEMP:-/tmp}/lychee-download" + +mkdir -p "${TEMP_DIR}" +cd "${TEMP_DIR}" + +curl -fsSLO "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_TAG}/${ARCHIVE}" +tar xzf "${ARCHIVE}" + +if [[ -f lychee ]]; then + BIN=lychee +elif [[ -f "lychee-${ARCH}-unknown-linux-gnu/lychee" ]]; then + BIN="lychee-${ARCH}-unknown-linux-gnu/lychee" +else + BIN="$(find . -maxdepth 2 -type f -name lychee | head -1)" +fi + +if [[ -z "${BIN}" || ! -f "${BIN}" ]]; then + echo "Error: could not locate lychee binary after extracting ${ARCHIVE}" + find . -maxdepth 3 -type f + exit 1 +fi + +mkdir -p "${HOME}/.local/bin" +install -m 755 "${BIN}" "${HOME}/.local/bin/lychee" +if [[ -n "${GITHUB_PATH:-}" ]]; then + echo "${HOME}/.local/bin" >> "${GITHUB_PATH}" +fi +lychee --version From 1e6bdac1128afa6ae5f0b6abb874bb1f2018511d Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Thu, 4 Jun 2026 21:43:21 -0500 Subject: [PATCH 06/10] fix(ci): export schema before lychee link check docs/Secretfile.schema.json is gitignored but linked from docs/schema.md. Generate it via ci-prepare-docs-links.sh before task docs:links and in CI workflows; document the published secret0.com URL as well. --- .github/workflows/docs.yaml | 7 +++---- .github/workflows/test.yaml | 11 +++++++++++ .mex/patterns/docs-links-lychee.md | 2 +- Taskfile.yml | 1 + docs/schema.md | 5 +++-- scripts/ci-install-lychee.sh | 1 + scripts/ci-prepare-docs-links.sh | 6 ++++++ 7 files changed, 26 insertions(+), 7 deletions(-) create mode 100755 scripts/ci-prepare-docs-links.sh diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index ee5e3fe..3109b50 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -31,16 +31,15 @@ jobs: run: | uv sync --frozen --all-extras + - name: Prepare generated doc artifacts for link check + run: bash ./scripts/ci-prepare-docs-links.sh + - name: Install lychee run: bash ./scripts/ci-install-lychee.sh - name: Check README.md and docs/ hyperlinks run: lychee --config lychee.toml README.md docs/ - - name: Export Secretfile schema for docs - run: | - uv run secretzero schema export --output docs/Secretfile.schema.json - - name: Build docs run: | uv run mkdocs build --clean diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 48266a7..1da03ba 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -20,6 +20,17 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Python 3.13 + uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 + with: + python-version: "3.13" + + - name: Set up uv + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 + + - name: Prepare generated doc artifacts for link check + run: bash ./scripts/ci-prepare-docs-links.sh + - name: Install lychee run: bash ./scripts/ci-install-lychee.sh diff --git a/.mex/patterns/docs-links-lychee.md b/.mex/patterns/docs-links-lychee.md index aed3431..80da510 100644 --- a/.mex/patterns/docs-links-lychee.md +++ b/.mex/patterns/docs-links-lychee.md @@ -16,7 +16,7 @@ last_updated: 2026-06-04 task docs:links ``` -Scans `README.md` and `docs/` using `lychee.toml` (loopback excluded, example URLs excluded). +Runs `scripts/ci-prepare-docs-links.sh` first (exports `docs/Secretfile.schema.json`, which is gitignored but linked from `docs/schema.md`). Then scans `README.md` and `docs/` using `lychee.toml` (loopback excluded, example URLs excluded). ## When it runs diff --git a/Taskfile.yml b/Taskfile.yml index 882d3e8..61597fd 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -175,6 +175,7 @@ tasks: echo "lychee not found. Install with: mise install (see mise.toml) or https://github.com/lycheeverse/lychee" exit 1 fi + bash ./scripts/ci-prepare-docs-links.sh lychee --config lychee.toml README.md docs/ docker:build: diff --git a/docs/schema.md b/docs/schema.md index 823cb9a..375d203 100644 --- a/docs/schema.md +++ b/docs/schema.md @@ -6,9 +6,10 @@ This document describes the complete schema for `Secretfile.yml`, the configurat Download or reference the published JSON Schema directly: -- [`Secretfile.schema.json`](Secretfile.schema.json) (same path on the deployed site as `/Secretfile.schema.json`) +- [`Secretfile.schema.json`](Secretfile.schema.json) in this repo’s `docs/` tree after `task docs:build` or `secretzero schema export --output docs/Secretfile.schema.json` +- Published copy: [secret0.com/Secretfile.schema.json](https://secret0.com/Secretfile.schema.json) -This file is generated during docs builds from `secretzero schema export`. +The `docs/` copy is generated (gitignored) from `secretzero schema export` before MkDocs builds and before `task docs:links`. Runtime validator and typing cleanups may not change schema field shape, but the generated schema remains the source-of-truth contract for machine consumers. diff --git a/scripts/ci-install-lychee.sh b/scripts/ci-install-lychee.sh index 36f9daa..ecc3ec7 100755 --- a/scripts/ci-install-lychee.sh +++ b/scripts/ci-install-lychee.sh @@ -35,3 +35,4 @@ if [[ -n "${GITHUB_PATH:-}" ]]; then echo "${HOME}/.local/bin" >> "${GITHUB_PATH}" fi lychee --version + diff --git a/scripts/ci-prepare-docs-links.sh b/scripts/ci-prepare-docs-links.sh new file mode 100755 index 0000000..f03e297 --- /dev/null +++ b/scripts/ci-prepare-docs-links.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +# Materialize generated doc artifacts required by lychee (not committed; see .gitignore). +set -euo pipefail + +uv sync --frozen +uv run secretzero schema export --output docs/Secretfile.schema.json From 77ca8bd1c44282fae81a2eb37755e751c1bb7949 Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Thu, 4 Jun 2026 21:46:47 -0500 Subject: [PATCH 07/10] fix(docs): link schema.md to committed root Secretfile.schema.json Lychee failed on docs/Secretfile.schema.json (gitignored, not in checkout). Point docs/schema.md at ../Secretfile.schema.json instead; drop uv prep from the lightweight test docs-links job. --- .github/workflows/docs.yaml | 6 +++--- .github/workflows/test.yaml | 11 ----------- .mex/patterns/docs-links-lychee.md | 2 +- Taskfile.yml | 1 - docs/schema.md | 7 +++---- scripts/ci-prepare-docs-links.sh | 3 ++- 6 files changed, 9 insertions(+), 21 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 3109b50..262da4b 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -31,15 +31,15 @@ jobs: run: | uv sync --frozen --all-extras - - name: Prepare generated doc artifacts for link check - run: bash ./scripts/ci-prepare-docs-links.sh - - name: Install lychee run: bash ./scripts/ci-install-lychee.sh - name: Check README.md and docs/ hyperlinks run: lychee --config lychee.toml README.md docs/ + - name: Export Secretfile schema for MkDocs + run: uv run secretzero schema export --output docs/Secretfile.schema.json + - name: Build docs run: | uv run mkdocs build --clean diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 1da03ba..48266a7 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -20,17 +20,6 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Python 3.13 - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 - with: - python-version: "3.13" - - - name: Set up uv - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 - - - name: Prepare generated doc artifacts for link check - run: bash ./scripts/ci-prepare-docs-links.sh - - name: Install lychee run: bash ./scripts/ci-install-lychee.sh diff --git a/.mex/patterns/docs-links-lychee.md b/.mex/patterns/docs-links-lychee.md index 80da510..7a336b5 100644 --- a/.mex/patterns/docs-links-lychee.md +++ b/.mex/patterns/docs-links-lychee.md @@ -16,7 +16,7 @@ last_updated: 2026-06-04 task docs:links ``` -Runs `scripts/ci-prepare-docs-links.sh` first (exports `docs/Secretfile.schema.json`, which is gitignored but linked from `docs/schema.md`). Then scans `README.md` and `docs/` using `lychee.toml` (loopback excluded, example URLs excluded). +`docs/schema.md` links to committed `../Secretfile.schema.json` (not gitignored `docs/Secretfile.schema.json`). CI may still run `scripts/ci-prepare-docs-links.sh` to materialize the MkDocs copy. Then scans `README.md` and `docs/` using `lychee.toml`. ## When it runs diff --git a/Taskfile.yml b/Taskfile.yml index 61597fd..882d3e8 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -175,7 +175,6 @@ tasks: echo "lychee not found. Install with: mise install (see mise.toml) or https://github.com/lycheeverse/lychee" exit 1 fi - bash ./scripts/ci-prepare-docs-links.sh lychee --config lychee.toml README.md docs/ docker:build: diff --git a/docs/schema.md b/docs/schema.md index 375d203..d2dd20d 100644 --- a/docs/schema.md +++ b/docs/schema.md @@ -6,10 +6,9 @@ This document describes the complete schema for `Secretfile.yml`, the configurat Download or reference the published JSON Schema directly: -- [`Secretfile.schema.json`](Secretfile.schema.json) in this repo’s `docs/` tree after `task docs:build` or `secretzero schema export --output docs/Secretfile.schema.json` -- Published copy: [secret0.com/Secretfile.schema.json](https://secret0.com/Secretfile.schema.json) - -The `docs/` copy is generated (gitignored) from `secretzero schema export` before MkDocs builds and before `task docs:links`. +- [`Secretfile.schema.json`](../Secretfile.schema.json) at the repository root (committed; refresh with `task schema:update`) +- MkDocs deploy copy under `docs/` (gitignored; generated via `secretzero schema export --output docs/Secretfile.schema.json` during `task docs:build`) +- Published site: [secret0.com/Secretfile.schema.json](https://secret0.com/Secretfile.schema.json) Runtime validator and typing cleanups may not change schema field shape, but the generated schema remains the source-of-truth contract for machine consumers. diff --git a/scripts/ci-prepare-docs-links.sh b/scripts/ci-prepare-docs-links.sh index f03e297..7728c8d 100755 --- a/scripts/ci-prepare-docs-links.sh +++ b/scripts/ci-prepare-docs-links.sh @@ -1,6 +1,7 @@ #!/usr/bin/env bash -# Materialize generated doc artifacts required by lychee (not committed; see .gitignore). +# Materialize gitignored MkDocs artifacts (optional for lychee; root Secretfile.schema.json is committed). set -euo pipefail uv sync --frozen uv run secretzero schema export --output docs/Secretfile.schema.json +test -f docs/Secretfile.schema.json From f14670ac8433a15abe3f318f639606a176e68bf6 Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Thu, 4 Jun 2026 21:55:53 -0500 Subject: [PATCH 08/10] fix(ci): exclude kubernetes.io from lychee (GHA connection failures) kubernetes.io docs URLs are valid but often fail with "connection failed" from GitHub Actions egress. Exclude the host and add retries/user-agent for other external links. --- .mex/patterns/docs-links-lychee.md | 7 ++++--- lychee.toml | 9 +++++++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/.mex/patterns/docs-links-lychee.md b/.mex/patterns/docs-links-lychee.md index 7a336b5..038eacc 100644 --- a/.mex/patterns/docs-links-lychee.md +++ b/.mex/patterns/docs-links-lychee.md @@ -28,9 +28,10 @@ task docs:links ## Fixing failures 1. Prefer fixing the URL (404/410) or pointing to `https://secret0.com` / `https://github.com/zloeber/SecretZero/issues` instead of disabled GitHub Discussions. -2. For intentional non-checkable URLs (localhost docs, placeholders), add a regex to `lychee.toml` `exclude` — do not disable the task. -3. Install tool: `mise install` (see `mise.toml` `lychee` tool). -4. CI installs via `scripts/ci-install-lychee.sh` (handles v0.24+ nested release tarballs; `lychee-action` v2.8.0 still expects a flat `lychee` binary). +2. For intentional non-checkable URLs (localhost docs, placeholders, CI-blocked hosts like `kubernetes.io`), add a regex to `lychee.toml` `exclude` — do not disable the task. +3. `kubernetes.io` links are valid but often fail lychee on GitHub Actions with "connection failed"; they remain excluded until upstream egress is reliable. +4. Install tool: `mise install` (see `mise.toml` `lychee` tool). +5. CI installs via `scripts/ci-install-lychee.sh` (handles v0.24+ nested release tarballs). ## Example manifest links diff --git a/lychee.toml b/lychee.toml index d183af4..7e7cd04 100644 --- a/lychee.toml +++ b/lychee.toml @@ -4,15 +4,20 @@ verbose = "warn" no_progress = true max_redirects = 10 -timeout = 25 +max_retries = 4 +retry_wait_time = 2 +timeout = 30 exclude_loopback = true include_mail = false +user_agent = "Mozilla/5.0 (compatible; SecretZeroDocsLinkCheck/1.0; +https://secret0.com)" -# Bot-blocked or example-only URLs (not doc defects) +# Bot-blocked, example-only, or CI-unreachable URLs (not doc defects) exclude = [ '^https://myvault\.vault\.azure\.net', '^https://jenkins\.example\.com', '^https://github\.com/yourusername/', '^https://gitlab\.com/-/profile/personal_access_tokens', '^https://www\.hhs\.gov/hipaa', + # kubernetes.io often returns "connection failed" from GitHub Actions egress; URLs work from normal clients. + '^https://kubernetes\.io/', ] From 9636a847c7577fc08c876ac59820e227961f44ab Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Fri, 5 Jun 2026 15:09:24 -0500 Subject: [PATCH 09/10] fix: update url scan exceptions --- lychee.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lychee.toml b/lychee.toml index 7e7cd04..b6b0aa2 100644 --- a/lychee.toml +++ b/lychee.toml @@ -20,4 +20,6 @@ exclude = [ '^https://www\.hhs\.gov/hipaa', # kubernetes.io often returns "connection failed" from GitHub Actions egress; URLs work from normal clients. '^https://kubernetes\.io/', + '^https://docs\.microsoft\.com', + '^https://docs\.aws\.amazon\.com', ] From f2f91e0490b17d2b7e1df5a20c7bd0e578054b24 Mon Sep 17 00:00:00 2001 From: Zachary Loeber Date: Fri, 5 Jun 2026 16:07:39 -0500 Subject: [PATCH 10/10] fix: security scan fixes, skill metadata --- .claude/skills/gitnexus/gitnexus-cli/SKILL.md | 2 ++ .claude/skills/gitnexus/gitnexus-debugging/SKILL.md | 2 ++ .claude/skills/gitnexus/gitnexus-exploring/SKILL.md | 2 ++ .claude/skills/gitnexus/gitnexus-guide/SKILL.md | 2 ++ .claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md | 2 ++ .claude/skills/gitnexus/gitnexus-refactoring/SKILL.md | 2 ++ .cursor/skills/gitnexus/gitnexus-cli/SKILL.md | 2 ++ .cursor/skills/gitnexus/gitnexus-debugging/SKILL.md | 2 ++ .cursor/skills/gitnexus/gitnexus-exploring/SKILL.md | 2 ++ .cursor/skills/gitnexus/gitnexus-guide/SKILL.md | 2 ++ .cursor/skills/gitnexus/gitnexus-impact-analysis/SKILL.md | 2 ++ .cursor/skills/gitnexus/gitnexus-refactoring/SKILL.md | 2 ++ .cursor/skills/ui-ux-pro-max/SKILL.md | 7 +++++++ .mex/ROUTER.md | 5 +++-- .mex/patterns/security-scan-remediation.md | 2 +- pyproject.toml | 2 +- uv.lock | 8 ++++---- 17 files changed, 40 insertions(+), 8 deletions(-) diff --git a/.claude/skills/gitnexus/gitnexus-cli/SKILL.md b/.claude/skills/gitnexus/gitnexus-cli/SKILL.md index c9e0af3..be3644d 100644 --- a/.claude/skills/gitnexus/gitnexus-cli/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-cli/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-cli description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\"" +metadata: + internal: true --- # GitNexus CLI Commands diff --git a/.claude/skills/gitnexus/gitnexus-debugging/SKILL.md b/.claude/skills/gitnexus/gitnexus-debugging/SKILL.md index 9510b97..931a66d 100644 --- a/.claude/skills/gitnexus/gitnexus-debugging/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-debugging/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-debugging description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\"" +metadata: + internal: true --- # Debugging with GitNexus diff --git a/.claude/skills/gitnexus/gitnexus-exploring/SKILL.md b/.claude/skills/gitnexus/gitnexus-exploring/SKILL.md index 927a4e4..161c891 100644 --- a/.claude/skills/gitnexus/gitnexus-exploring/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-exploring/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-exploring description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\"" +metadata: + internal: true --- # Exploring Codebases with GitNexus diff --git a/.claude/skills/gitnexus/gitnexus-guide/SKILL.md b/.claude/skills/gitnexus/gitnexus-guide/SKILL.md index 937ac73..f0eb511 100644 --- a/.claude/skills/gitnexus/gitnexus-guide/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-guide/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-guide description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\"" +metadata: + internal: true --- # GitNexus Guide diff --git a/.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md b/.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md index e19af28..f0e36e8 100644 --- a/.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-impact-analysis description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\"" +metadata: + internal: true --- # Impact Analysis with GitNexus diff --git a/.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md b/.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md index f48cc01..648a2da 100644 --- a/.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-refactoring description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\"" +metadata: + internal: true --- # Refactoring with GitNexus diff --git a/.cursor/skills/gitnexus/gitnexus-cli/SKILL.md b/.cursor/skills/gitnexus/gitnexus-cli/SKILL.md index c9e0af3..be3644d 100644 --- a/.cursor/skills/gitnexus/gitnexus-cli/SKILL.md +++ b/.cursor/skills/gitnexus/gitnexus-cli/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-cli description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\"" +metadata: + internal: true --- # GitNexus CLI Commands diff --git a/.cursor/skills/gitnexus/gitnexus-debugging/SKILL.md b/.cursor/skills/gitnexus/gitnexus-debugging/SKILL.md index 9510b97..931a66d 100644 --- a/.cursor/skills/gitnexus/gitnexus-debugging/SKILL.md +++ b/.cursor/skills/gitnexus/gitnexus-debugging/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-debugging description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\"" +metadata: + internal: true --- # Debugging with GitNexus diff --git a/.cursor/skills/gitnexus/gitnexus-exploring/SKILL.md b/.cursor/skills/gitnexus/gitnexus-exploring/SKILL.md index 927a4e4..161c891 100644 --- a/.cursor/skills/gitnexus/gitnexus-exploring/SKILL.md +++ b/.cursor/skills/gitnexus/gitnexus-exploring/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-exploring description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\"" +metadata: + internal: true --- # Exploring Codebases with GitNexus diff --git a/.cursor/skills/gitnexus/gitnexus-guide/SKILL.md b/.cursor/skills/gitnexus/gitnexus-guide/SKILL.md index 937ac73..f0eb511 100644 --- a/.cursor/skills/gitnexus/gitnexus-guide/SKILL.md +++ b/.cursor/skills/gitnexus/gitnexus-guide/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-guide description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\"" +metadata: + internal: true --- # GitNexus Guide diff --git a/.cursor/skills/gitnexus/gitnexus-impact-analysis/SKILL.md b/.cursor/skills/gitnexus/gitnexus-impact-analysis/SKILL.md index e19af28..f0e36e8 100644 --- a/.cursor/skills/gitnexus/gitnexus-impact-analysis/SKILL.md +++ b/.cursor/skills/gitnexus/gitnexus-impact-analysis/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-impact-analysis description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\"" +metadata: + internal: true --- # Impact Analysis with GitNexus diff --git a/.cursor/skills/gitnexus/gitnexus-refactoring/SKILL.md b/.cursor/skills/gitnexus/gitnexus-refactoring/SKILL.md index f48cc01..648a2da 100644 --- a/.cursor/skills/gitnexus/gitnexus-refactoring/SKILL.md +++ b/.cursor/skills/gitnexus/gitnexus-refactoring/SKILL.md @@ -1,6 +1,8 @@ --- name: gitnexus-refactoring description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\"" +metadata: + internal: true --- # Refactoring with GitNexus diff --git a/.cursor/skills/ui-ux-pro-max/SKILL.md b/.cursor/skills/ui-ux-pro-max/SKILL.md index f53d42b..92124be 100644 --- a/.cursor/skills/ui-ux-pro-max/SKILL.md +++ b/.cursor/skills/ui-ux-pro-max/SKILL.md @@ -1,3 +1,10 @@ +--- +name: ui-ux-pro-max +description: Comprehensive design guide for web and mobile applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 13 technology stacks. Searchable database with priority-based recommendations. +metadata: + internal: true +--- + # ui-ux-pro-max Comprehensive design guide for web and mobile applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 13 technology stacks. Searchable database with priority-based recommendations. diff --git a/.mex/ROUTER.md b/.mex/ROUTER.md index 94aa363..4840057 100644 --- a/.mex/ROUTER.md +++ b/.mex/ROUTER.md @@ -14,7 +14,7 @@ edges: condition: when setting up the dev environment or running the project for the first time - target: patterns/INDEX.md condition: when starting a task — check the pattern index for a matching pattern file -last_updated: 2026-05-27 +last_updated: 2026-06-05 --- # Session Bootstrap @@ -56,6 +56,7 @@ Then read this file fully before doing anything else in this session. - **Terraform static-variable behavior:** Terraform export now always emits sensitive input variables for static-like secrets (`static` and bundle kinds with `PROMPTS_LIKE_STATIC`, such as `azure_app_reg`). `--include-static-secrets` now controls whether static defaults are embedded as Terraform variable defaults. - **Agent absolute rule (skills):** `skills/secretzero/SKILL.md` — never consume secrets in LLM/tool context; use SecretZero only for discovery, authoring, seeding, sync, and human entry (`web` / `agent sync --web`). All focused skills inherit this rule. - **Agent skill guidance split:** SecretZero guidance is now split into focused skills — `skills/secretzero-author/SKILL.md` (schema-compliant Secretfile authoring, **guided session** with manifest-root confirmation, inventory table, add/edit loop with generator/target menus, optional `detect`/`discover`, optional background `secretzero web`, Hermes + MCP guidance, `.szvar` lane breakout, and policy-bound targets), `skills/secretzero-agent/SKILL.md` (agentic vectors, runtime/API workflows, and installation/onboarding), `skills/secretzero-handle/SKILL.md` (`SZ_AGENT_MODE`, `.env`/ingest preseed, spill-safe CLI), and `skills/secretzero-agent-adopt/SKILL.md` (Hermes/OpenClaw `agent list` / `agent adopt` bootstrap and restore loops). +- **Internal vs public skills:** Only `skills/**/SKILL.md` files are published for remote install (Hermes/raw URLs). All other repo `SKILL.md` files (`.cursor/skills/**`, `.claude/skills/**`) must include `metadata: internal: true` in frontmatter. - **`secretzero agent list` / `agent adopt`:** Discover local Hermes/OpenClaw installs (read-only) and bootstrap SecretZero environments from **present** catalog credentials without emitting values. `agent adopt` writes `Secretfile.yml` into `--output-dir` (default: agent install path); `agent backup` is an alias. Supports `--template`, `--preseed-lockfile`, autodetect (Hermes then OpenClaw), and idempotent merge on re-adopt. See `docs/superpowers/specs/2026-05-27-agent-adopt-design.md`, `.mex/patterns/agent-adopt.md`. - **`secretzero agent instructions`:** Read-only Rich/JSON report of `agent_instructions` (summary + numbered steps). Default scope is pending manual secrets (same semantics as `agent sync`); `--all` lists every secret with instructions; `--detailed` adds optional metadata. See `.mex/patterns/agent-instructions-report.md`. - **Environment-map lanes + target profiles:** Secretfile now supports top-level `environments` and `target_profiles`; CLI (`sync`, `agent sync`, `web`) and API (`/sync`, `/agent/sync`) resolve lane-specific var files/lockfiles/profile defaults with runtime flags taking precedence. `secretzero web` now renders an environment dropdown and recomputes lane context on selection. @@ -84,7 +85,7 @@ Then read this file fully before doing anything else in this session. - **CLI version subcommand:** Added `secretzero version` with `--detailed` runtime metadata and `--format` output selection (`text`, `json`, `yaml`) for both human and agent-friendly version reporting. - **CLI status compact mode:** Default `secretzero status` text output is now a compact color-coded secret→target mapping; prior full status report moved to `secretzero status --detailed` (`--verbose` implies `--detailed`). - **CLI status/provider readiness + clean command:** Compact status now uses provider connectivity preflight in addition to identity to classify unsynced targets (local/file no longer misclassified as unknown when connectivity succeeds). Added `secretzero clean` for lockfile orphan cleanup without running sync (`--dry-run`, `--format text|json`). -- **Supply-chain hardening defaults:** CI/workflows now install `uv` via SHA-pinned `astral-sh/setup-uv`, use frozen dependency resolution (`uv sync --frozen ...`) in release/test/docs/agent pre-commit paths, pin PyPI publish action to a specific commit SHA, avoid mutable `wrangler@latest` installs in docs publishing, and keep `tool.uv.override-dependencies` floors current for pip-audit (including `langsmith>=0.8.0` for CVE-2026-45134 and `starlette>=1.0.1` for PYSEC-2026-161). +- **Supply-chain hardening defaults:** CI/workflows now install `uv` via SHA-pinned `astral-sh/setup-uv`, use frozen dependency resolution (`uv sync --frozen ...`) in release/test/docs/agent pre-commit paths, pin PyPI publish action to a specific commit SHA, avoid mutable `wrangler@latest` installs in docs publishing, and keep `tool.uv.override-dependencies` floors current for pip-audit (including `pip>=26.1.2` for PYSEC-2026-196, `langsmith>=0.8.0` for CVE-2026-45134, and `starlette>=1.0.1` for PYSEC-2026-161). - **Schema/docs parity guardrail:** Any Secretfile-facing model/config change must follow `.mex/patterns/schema-doc-parity.md` to keep `task schema:update`, `docs/schema.md`, `docs/user-guide/configuration/index.md`, tests, and example manifests in sync. - **Lockfile state parity guardrail:** Sync-state evaluation (`synced`/`pending`/`drift`) must be implemented once in `src/secretzero/lockfile_state.py` and reused by dashboard/graph/CLI render layers; do not duplicate target-hash fallback logic in UI code. diff --git a/.mex/patterns/security-scan-remediation.md b/.mex/patterns/security-scan-remediation.md index 93fb6d8..ef31116 100644 --- a/.mex/patterns/security-scan-remediation.md +++ b/.mex/patterns/security-scan-remediation.md @@ -11,7 +11,7 @@ edges: condition: "When scan failures may be caused by environment/bootstrap drift" - target: "patterns/add-cli-command.md" condition: "When security findings come from CLI behavior changes" -last_updated: 2026-05-12 +last_updated: 2026-06-05 --- # Security Scan Remediation diff --git a/pyproject.toml b/pyproject.toml index e3161b8..e124b6f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -54,7 +54,7 @@ override-dependencies = [ "langsmith>=0.8.0", "lxml>=6.1.0", "ollama>=0.6.2", - "pip>=26.0.2", + "pip>=26.1.2", "pyjwt>=2.13.0", "pymdown-extensions>=10.21.3", "pytest>=9.0.3", diff --git a/uv.lock b/uv.lock index be1e0ef..286a7ec 100644 --- a/uv.lock +++ b/uv.lock @@ -36,7 +36,7 @@ overrides = [ { name = "langsmith", specifier = ">=0.8.0" }, { name = "lxml", specifier = ">=6.1.0" }, { name = "ollama", specifier = ">=0.6.2" }, - { name = "pip", specifier = ">=26.0.2" }, + { name = "pip", specifier = ">=26.1.2" }, { name = "pyjwt", specifier = ">=2.13.0" }, { name = "pymdown-extensions", specifier = ">=10.21.3" }, { name = "pytest", specifier = ">=9.0.3" }, @@ -2304,11 +2304,11 @@ wheels = [ [[package]] name = "pip" -version = "26.1" +version = "26.1.2" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/73/7e/d2b04004e1068ad4fdfa2f227b839b5d03e602e47cdbbf49de71137c9546/pip-26.1.tar.gz", hash = "sha256:81e13ebcca3ffa8cc85e4deff5c27e1ee26dea0aa7fc2f294a073ac208806ff3", size = 1840316, upload-time = "2026-04-26T21:00:05.406Z" } +sdist = { url = "https://files.pythonhosted.org/packages/01/91/47e7d486260f618783899587af63ccf7980fb60245c3e63dd4571c6b57ad/pip-26.1.2.tar.gz", hash = "sha256:f49cd134c61cf2fd75e0ce2676db03e4054504a5a4986d00f8299ae632dc4605", size = 1840799, upload-time = "2026-05-31T17:33:58.56Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/70/7a/be4bd8bcbb24ea475856dd68159d78b03b2bb53dae369f69c9606b8888f5/pip-26.1-py3-none-any.whl", hash = "sha256:4e8486d821d814b77319acb7b9e8bf5a4ee7590a643e7cb21029f209be8573c1", size = 1812804, upload-time = "2026-04-26T21:00:03.194Z" }, + { url = "https://files.pythonhosted.org/packages/5d/95/6b5cb3461ea5673ba0995989746db58eb18b91b54dbf331e72f569540946/pip-26.1.2-py3-none-any.whl", hash = "sha256:382ff9f685ee3bc25864f820aa50505825f10f5458ffff07e30a6d96e5715cab", size = 1813144, upload-time = "2026-05-31T17:33:56.772Z" }, ] [[package]]