/security-setup

name: security-setup
description: "Install local-first security hardening: pre-commit secret detection, offline dependency scans, static analysis, reports, and gated free CI. Use when hardening repos or adding security hooks. Don't use for incident response or cloud security reviews."
license: MIT
compatibility: "Cross-platform (macOS, Linux, Windows). Requires git, Python 3.8+, and project write access. Uses pre-commit plus free local tools such as gitleaks, trivy, semgrep, bandit, or cargo-audit when appropriate. Semgrep on Windows requires WSL2."
effort: high
metadata:
  version: 1.5.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

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