Security Setup

Install a local-first security hardening stack for a project. Favor checks that run offline at hook time, produce machine-readable output, and give developers a clear summary before code leaves their machine.

<!-- Maintainer note — not runtime guidance: keep this orchestrator short for the agent's context budget; detailed matrices, templates, and long verification scenarios live in `references/`. Link, don't inline. -->

This skill may trigger automatically per its description, but it never writes silently: Phase 1 always dry-runs the planned changes and waits for explicit user confirmation before touching files, and Phase 2 (CI) only runs when the user explicitly asks for it (e.g. --ci).

Prerequisites

• Git repo with a branch you can commit to.
• Python 3.8+ and pip.
• Permission to create .pre-commit-config.yaml, scripts/, security/, SECURITY.md.
• (Optional for --ci) GitHub Actions enabled on the repo.
• Network for initial tool/db installs (subsequent hook runs are offline).

Check these before Phase 1:

1. Run git rev-parse --git-dir. If it exits non-zero, stop and end with a BLOCKED final report.
2. Run python3 --version (python --version on Windows). If no interpreter answers, or the version is below 3.8, stop and end with a BLOCKED final report.
3. If a selected tool cannot run offline, record the gap for SECURITY.md and the final report. Do not claim offline coverage for it.

Repo Sync Before Edits (mandatory)

Before creating/updating/deleting files in an existing repository, sync the current branch with remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first as a backup, sync, then restore:

git stash push -u -m "pre-sync"           # backup local changes
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop                              # rollback by restoring the backup

If origin is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing. Never use --force rollback options without confirmation.

Operating Model

Work in two gated phases:

1. Local security baseline - install a pre-commit hook that checks secrets, dependency vulnerabilities, and static analysis issues locally.
2. CI/CD mirror - only when the user asks for --ci, create a free-tier GitHub Actions workflow that runs the same local runner on pull requests.

Do not create CI files until Phase 1 is installed and passing.

Phase 1 - Local Security Baseline

1. Detect the Project

Inspect the repo before choosing tools. The runner and skill instructions work on macOS, Linux, and Windows; pick the matching shell snippet.

macOS / Linux (bash, zsh):

ls -la package.json package-lock.json pnpm-lock.yaml yarn.lock pyproject.toml requirements.txt Cargo.toml Cargo.lock go.mod pom.xml build.gradle 2>/dev/null
ls -la .pre-commit-config.yaml SECURITY.md .github/workflows/security.yml 2>/dev/null
command -v gitleaks trivy semgrep detect-secrets bandit cargo-audit pre-commit 2>/dev/null

Windows PowerShell:

Get-ChildItem -Force -ErrorAction SilentlyContinue package.json,package-lock.json,pnpm-lock.yaml,yarn.lock,pyproject.toml,requirements.txt,Cargo.toml,Cargo.lock,go.mod,pom.xml,build.gradle
Get-ChildItem -Force -ErrorAction SilentlyContinue .pre-commit-config.yaml,SECURITY.md,.github\workflows\security.yml
foreach ($t in 'gitleaks','trivy','semgrep','detect-secrets','bandit','cargo-audit','pre-commit') { Get-Command $t -ErrorAction SilentlyContinue }

Identify:

• Languages and lockfiles
• Existing pre-commit config and security docs
• Available local tools
• Whether the repo is public or private, if CI/SARIF upload is requested

Use references/tool-selection.md for the tool matrix and install commands.

2. Select the Minimal Tool Set

Choose the smallest useful set:

• Secrets: prefer gitleaks; use detect-secrets when it already exists in a Python-heavy repo.
• Dependencies: prefer trivy fs --skip-db-update for offline hook runtime; add cargo-audit only for Rust repos that already use Cargo.
• Static analysis: prefer semgrep with local rules under security/. Add language-native scanners only when the language is present (bandit for Python, gosec for Go, cargo clippy/cargo audit for Rust).

Supply-chain install guardrail

When the repo uses package managers, recommend Socket Firewall as a lightweight local guardrail for day-to-day dependency installs. This does not replace lockfile scanning with trivy/cargo-audit; it shifts risk left by making risky installs harder before a new dependency reaches the repo.

For macOS/Linux users on zsh or bash, suggest adding these aliases to the developer shell profile:

alias npm="sfw npm"
alias yarn="sfw yarn"
alias pnpm="sfw pnpm"
alias pip="sfw pip"
alias uv="sfw uv"
alias cargo="sfw cargo"

Only include aliases for package managers the project actually uses, and document the guardrail in SECURITY.md as optional local developer setup. If Socket Firewall is not installed, print the official install instructions or link to the official docs; do not add failing hooks that require sfw.

The hook must not call cloud services at runtime. If a scanner needs a local database, warm that database during setup and run with offline flags in the hook. If offline dependency scanning cannot be configured for an ecosystem, document the gap in SECURITY.md and do not pretend the criterion is satisfied.

File-aware scoping (per-check triggers)

Pre-commit must be fast on small commits without losing coverage. Each check declares its own relevance rule — never a global "skip on .md only" filter.

Trigger semantics in security/security-tools.json:

Trigger	Behavior
"always": true	Always run. Use for secret scanners — secrets land in .md, .json, .env.example, Dockerfile, anywhere.
"paths": [globs]	Run only when at least one staged file matches a glob. Use for lockfile-driven (trivy, cargo-audit) or language-driven (semgrep, bandit) checks.
(omitted)	Runner falls back to the per-tool defaults baked into scripts/security_check.py for the recognized tool name.

A repo-wide trip_all_paths list (default: .pre-commit-config.yaml, security/**, .github/workflows/**, Dockerfile*, .dockerignore, scripts/security_check.py) forces every applicable check to run when any of those files is staged. This catches workflow-injection edits, hook-tampering, and Dockerfile RCE that would otherwise slip past purely category-based scoping.

CI runs full scans (--all). Scoping only applies on developer commits; the CI mirror is the safety net.

Mandatory invariant: secret scanning runs on every commit. Do not move gitleaks (or its replacement) into a path-restricted trigger.

3. Generate Local Files

Dry-run the changes before writing any file:

1. List every target path below and mark each one new or exists.
2. For each exists target, show the diff between the current file and the planned content.
3. Ask the user to confirm the list. Name .pre-commit-config.yaml and SECURITY.md explicitly when they exist: overwriting either one is destructive.
4. If the user declines every file, write nothing and end with a BLOCKED final report. If the user declines some files, write only the confirmed ones and record each declined file for the final report.
5. Before changing an exists target, copy it to <path>.bak so the user can roll back.

Create or update these files:

• .pre-commit-config.yaml - merge a local security-check hook into existing config; do not overwrite user hooks.
• scripts/security_check.py - copy from scripts/security_check.py in this skill, then adjust tool config if needed.
• security/semgrep-rules.yml - local Semgrep rules so runtime scans are offline.
• security/security-tools.json - selected tools and command overrides.
• SECURITY.md - summary of selected tools, why they were chosen, and how to run or bypass checks.

Use references/templates.md for starter snippets.

4. Bypass Policy

Never add a silent bypass. Bypass cannot be performed through git commit because pre-commit redirects hook stdin to /dev/null, so the runner's TTY check refuses --force from inside the hook. The approved bypass is a two-step, explicit override:

1. Run the runner directly with --force and type YES at the prompt:

   # macOS / Linux
   SECURITY_CHECK_ARGS=--force python3 scripts/security_check.py
   

   # Windows PowerShell
   $env:SECURITY_CHECK_ARGS = "--force"; python scripts\security_check.py; Remove-Item Env:SECURITY_CHECK_ARGS
   

   :: Windows cmd.exe
   set SECURITY_CHECK_ARGS=--force && python scripts\security_check.py && set SECURITY_CHECK_ARGS=
   

   The runner prints the prompt:

   Type YES to override security checks and force-push:
   

   It accepts only the literal string YES. Any other input, EOF, or a non-TTY context exits non-zero and refuses the bypass.

2. After the override is recorded in the report, commit with git commit --no-verify. Document the bypass in SECURITY.md (date, reason, link to the recorded report) so the override is auditable.

Do not add --force to the pre-commit hook entry, and do not wrap git commit in a script that opens /dev/tty for the hook — both routes hide the bypass from review.

5. Verify Locally

Run the local checks after writing files. Use python3 on macOS/Linux and python on Windows (the Python launcher routes to the active interpreter). Verification uses --all so every configured check runs regardless of what happens to be staged.

First run pre-commit --version. If it exits non-zero, print the install commands below, run only the security_check.py command, skip pre-commit run, and end with a PARTIAL final report that names the missing pre-commit:

python3 -m pip install pre-commit   # use `python` on Windows
pre-commit install

If it exits 0, run both verification commands and record each exit code:

# macOS / Linux
python3 scripts/security_check.py --all --no-fail-on-missing-tools
pre-commit run security-check --all-files

# Windows PowerShell
python scripts\security_check.py --all --no-fail-on-missing-tools
pre-commit run security-check --all-files

When run from a pre-commit hook with no flags, the runner inspects git diff --cached and scopes checks to the staged file set per the trigger table in §2. --all overrides this for verification or one-off full scans; --staged-only errors if no staged files are found (useful for guarded hooks).

Exit codes: 0 means no failing finding (or an accepted bypass), 1 means at least one fail_on finding, and 2 means the runner could not run (an invalid security-tools.json, --staged-only with nothing staged, or an unwritable report path); its stderr message names the input and the fix.

Expected output

A successful first run prints a summary to stdout and exits 0. See "Report Requirements" below for the exact shape and content of that summary.

Assert: a clean run exits 0, both report paths exist, and security-report.json parses as valid JSON with a top-level summary object. Any HIGH or CRITICAL finding exits non-zero unless the bypass in §"4. Bypass Policy" was completed.

Phase 2 - CI/CD Mirror (--ci)

Only run this phase when the user asks for CI/CD, for example /security-setup --ci.

Preconditions:

• Phase 1 files exist
• python3 scripts/security_check.py --all --no-fail-on-missing-tools exits 0 locally
• .pre-commit-config.yaml contains the security-check hook

If any precondition fails, do not create the workflow; record CI not created and the failing precondition for the final report.

Otherwise create .github/workflows/security.yml using references/templates.md. If that file already exists, apply the Step 3 dry-run steps to it first (diff, confirm, .bak backup). Keep the workflow free-tier friendly:

• Trigger on pull_request and push to the default branch.
• Install only the selected tools.
• Cache scanner databases where supported.
• Run python3 scripts/security_check.py --all (CI always full-scans).
• Upload SARIF only when the repo can use GitHub Code Scanning; otherwise keep the job summary only.

Report Requirements

The local runner must print a concise report with:

• Total checks run
• Findings by category: secrets, dependencies, static analysis, tool errors
• Severity breakdown: critical, high, medium, low, info
• Actionable fix hints
• Paths to JSON and Markdown report artifacts

The default exit behavior is strict: any HIGH or CRITICAL finding exits non-zero.

A successful full run looks like this (exact counts vary):

Security Check Summary
======================
Mode: full
Checks run: 3 of 3 (skipped: 0)
Findings: 1
Severity: HIGH=1
Categories: dependencies=1
JSON report: security/security-report.json
Markdown report: security/security-report.md

Top findings:
- HIGH [dependencies/trivy] CVE-XXXX-XXXX in <pkg> (<lockfile>)
  Hint: Upgrade to <version>.

A scoped run on a docs-only commit looks like:

Mode: staged
Staged files: 2
Checks run: 1 of 3 (skipped: 2)
Skipped: trivy, semgrep

Skipped checks are recorded in both reports with their scope reason — they are not silent.

Acceptance Criteria

A completed setup passes when:

• .pre-commit-config.yaml contains a local security-check hook.
• scripts/security_check.py exists and prints the required summary.
• Secret detection, dependency scanning, and static analysis are configured for the detected project where offline local tooling is available.
• Hook runtime uses offline flags and does not require cloud credentials.
• --force requires the exact YES confirmation before bypassing failures.
• SECURITY.md documents selected tools, omissions, run commands, and CI status.
• --ci creates .github/workflows/security.yml only after Phase 1 passes.
• File-aware scoping has been walked through manually against the no-blindspot scenarios in references/verification-scenarios.md.
• The final report passes the reader checks in references/final-report.md: the status is on the first line, verified checks are separated from assumptions, each claim cites a command or file, and the next decision is named. Human understanding stays unconfirmed until the user gives feedback.

Edge Cases

• Existing hooks: merge the new hook; preserve all existing hooks and revs.
• Monorepo: use path filters in security/security-tools.json and document per-package coverage.
• Missing tools: print the install command from references/tool-selection.md for each missing selected tool, and install it only after the user confirms. A category whose tool stays missing is listed in the final report; never skip it silently.
• Private repo SARIF: GitHub Code Scanning may require a paid plan. Keep the summary report and skip SARIF upload unless available.
• Network-restricted setup: create configs and report the commands that must be run later to warm vulnerability databases.

Step Completion Report

After each phase, report:

◆ Security Setup ([phase] - [context])
................................................................
  Project detection:      pass | fail - detail
  Tool selection:         pass | fail - detail
  Local hook:             pass | fail - detail
  Security report:        pass | fail - detail
  CI mirror:              pass | skipped | fail - detail
  Criteria:               N/M met
  ____________________________
  Result:                 PASS | PARTIAL | FAIL

Final Report

End every run, including a stop, with one final report in the shape references/final-report.md defines. Read it before writing the report. The four parts are required, in this order:

1. Result: — COMPLETE, PARTIAL — <reason>, or BLOCKED — <reason>, then one line on what changed.
2. Evidence: — only commands that ran, with exit codes, and each file written with its .bak path.
3. Uncertainty: — missing tools, offline gaps, declined files, and checks that did not run.
4. Decision: — the approval the user must give, or No approval needed., then each remaining user action.

Resources

• references/tool-selection.md - offline-first tool matrix and install notes
• references/templates.md - target repo file templates
• references/verification-scenarios.md - no-blindspot manual verification scenarios
• references/final-report.md - final report parts, status rules, and examples
• scripts/security_check.py - reusable local security summary runner
• evals/evals.json - trigger and behavior eval cases with final-report assertions