Repo Hardening

Artifact Model

Default output directory in the target repo:

.repo-hardening/

Default generated files:

• inventory.json
• audit.md
• hardening-plan.md

If the repo already uses a canonical location such as security/, you may override the output path explicitly. See references/artifact-layout.md.

Audit Workflow

1. Run the deterministic inventory:

python3 skills/repo-hardening/scripts/repo_inventory.py <repo-path>

Optional incident-package checks:

python3 skills/repo-hardening/scripts/repo_inventory.py <repo-path> --package axios --package litellm

Optional output override:

python3 skills/repo-hardening/scripts/repo_inventory.py <repo-path> --out-dir security

2. Read the generated artifacts in the target repo:

• inventory.json for raw evidence
• audit.md for findings
• hardening-plan.md for prioritized work

3. Load references/hardening-matrix.md for stack-specific remediation choices.

4. Explain the findings in this order:

5. current exposure

6. highest-value fixes

7. residual risk

Hardening Workflow

1. Run the inventory first if current artifacts do not exist or are stale.
2. Apply the minimum safe hardening changes for the repo's stack:

• Node: pnpm install --frozen-lockfile or npm ci, pinned packageManager, pinned GitHub Action SHAs
• Python: uv sync --frozen or hash-verified requirements installs
• GitHub Actions: explicit top-level permissions:, no mutable uses: refs
• GitLab CI: reduce fresh installs, pin reusable includes when practical
• Bot workflows: reduce write scopes and remove install-capable tool grants unless justified
• Remote bootstrap/downloads: replace latest and curl | sh style flows with pinned or verified retrieval

3. Run the repo's own checks and tests.
4. Refresh the generated artifacts so they reflect post-change state.
5. Report exactly what changed, what was verified, and what remains.

Output Requirements

When returning results to the user:

• lead with the highest-risk findings or the highest-value fixes
• include concrete file references when discussing changes
• state what verification actually ran
• state what remains local-only, uncommitted, or unpushed

When updating the repo-local artifacts:

• keep findings concise and evidence-backed
• separate current state from planned work
• distinguish completed fixes from residual backlog

Verification

• Run the target repo's native lint, build, and test commands before calling the hardening pass complete.
• Re-run python3 skills/repo-hardening/scripts/repo_inventory.py <repo-path> after changes so the repo-local artifacts reflect the post-change state.
• If workflow files changed, confirm there are no mutable uses: refs and no missing top-level permissions: blocks.
• If install paths changed, confirm the repo now uses a frozen or hash-verified form in CI.

Boundaries

• Do not assume every repo should adopt the same package manager or CI shape.
• Do not rewrite repo history or revert unrelated local work.
• Do not claim a repo is hardened without rerunning native verification.
• Do not create or delete repo-local security directories unless the user asked; use .repo-hardening/ by default.
• Do not silently remove bot workflows; that is a product decision unless the user asked for removal.

Commands

• /repo-audit
• /repo-harden

References

• references/hardening-matrix.md
• references/artifact-layout.md