--- name: security-detection description: Detect infrastructure and security-critical file changes to trigger security agent review recommendations ensuring proper security oversight for sensitive modifications. Use when you ask "did I touch security-critical files", "should the security agent review this". Detection only. Do NOT use to scan source for injection patterns (use security-scan). license: MIT metadata: routing: role: front-door invoker: autoplan trigger: autoplan routes did-I-touch-security-critical-files questions to security-detection user-facing: false version: 1.0.0 model: haiku model-rationale: cost. The 'haiku' rolling alias resolves via the platform model_tiers map to a tier priced below the sonnet-tier harness default; this unit is routing/mechanical work where the cheaper tier suffices (ADR-080 rule 3). --- # Security Detection Utility ## Triggers | Trigger Phrase | Operation | |----------------|-----------| | `scan for security changes` | detect-infrastructure with staged files | | `check security-critical files` | detect-infrastructure with file list | | `does this change need security review` | detect-infrastructure analysis | | `do I need a security review` | Risk-level assessment of changed files | | `check infrastructure changes` | Pattern matching against critical/high lists | --- ## When to Use Use this skill when: - Committing changes that may touch infrastructure or security files - Pre-commit validation for security-sensitive paths - Determining if a security agent review is needed - CI pipeline security gate checks Use the security agent directly instead when: - You already know security review is needed - Performing threat modeling or vulnerability assessment - Reviewing authentication or authorization code in depth --- ## Available Scripts | Script | Language | Usage | |--------|----------|-------| | `detect_infrastructure.py` | Python 3 | Cross-platform | ## Usage ```bash # Analyze staged files python detect_infrastructure.py --use-git-staged # Analyze specific files python detect_infrastructure.py --files .github/workflows/ci.yml src/auth/login.cs ``` ## Output **Delegation on each host.** "Delegate to the `X` agent" means the host's subagent tool: Claude Code `Task` with `subagent_type="X"`; Copilot CLI `task` with `agent_type="project-toolkit:X"`; Codex `spawn_agent` with `agent_type="X"`, plus `fork_turns="none"` when the agent reviews or judges work (the default hands it your whole history); Muse Code `subagent_spawn` with `role="X"` and an `objective`, plus `worktree_isolation: true` for an agent that writes files. If the host has no subagent tool, or no `X` agent is installed, run the step yourself in this session. When security-critical files are detected: ```text === Security Review Detection === CRITICAL: Security agent review REQUIRED Matching files: [CRITICAL] .github/workflows/deploy.yml [HIGH] src/Controllers/AuthController.cs Run security agent before implementation: Delegate to the security agent: "Review infrastructure changes" (Claude Code: Task with subagent_type="security"; Copilot CLI: task with agent_type="project-toolkit:security"; Codex: spawn_agent with agent_type="security"; Muse Code: subagent_spawn with role="security") ``` When no matches: ```text No infrastructure/security files detected. ``` ## Risk Levels | Level | Meaning | Action | |-------|---------|--------| | CRITICAL | Immediate security implications | Review REQUIRED | | HIGH | Potential security impact | Review RECOMMENDED | ## Detected Patterns ### Critical (Review Required) - CI/CD workflows (`.github/workflows/*`) - Git hook configuration (`{lefthook,.lefthook,lefthook-local,.lefthook-local}.{yml,yaml,json,jsonc,toml}`, `.config/{lefthook,lefthook-local}.{yml,yaml,json,jsonc,toml}`, `.husky/*`) - Git hook policy (`scripts/validation/git_hook_policy.py`) - Authentication code (`**/Auth/**`, `**/Security/**`) - Environment files (`*.env*`) - Credentials and keys (`*.pem`, `*.key`, `*secret*`) ### High (Review Recommended) - Build scripts (`build/**/*.ps1`, `scripts/**/*.sh`) - Container configs (`Dockerfile*`, `docker-compose*`) - API controllers (`**/Controllers/**`) - App configuration (`appsettings*.json`) - Infrastructure as Code (`*.tf`, `*.tfvars`, `*.bicep`) ## Integration ### Pre-commit Hook Add a named validator job to `lefthook.yml`: ```bash # Security detection (non-blocking warning) ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/security-detection/detect_infrastructure.py --use-git-staged; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) ``` ### CI Integration On a Linux pull-request runner, pass the changed paths explicitly. CI checkouts do not have a staged diff. ```yaml - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 - name: Check security-critical files shell: bash env: BASE_SHA: ${{ github.event.pull_request.base.sha }} HEAD_SHA: ${{ github.sha }} run: >- git diff --no-renames --name-only -z "$BASE_SHA" "$HEAD_SHA" | ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/security-detection/detect_infrastructure.py --files-from-stdin; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) ``` ## Exit Codes | Code | Meaning | |------|---------| | 0 | Detection finished. Matches print a warning that does not block. With `--require-security-review`, also: no CRITICAL file, or every CRITICAL file has a valid security review marker. | | 1 | `--require-security-review` is set and a CRITICAL file has no valid marker on the ref (BLOCKED). | | 3 | `--require-security-review` is set and git could not answer while reading the staged index or the review marker (git missing, timed out, exited non-zero, returned undecodable output, or rejected the ref) (BLOCKED). An unanswered check never counts as a marker. | Without `--require-security-review` the scripts always exit 0, so advisory use in commits and CI stays non-blocking. The warning is informational only. Only the flag turns a CRITICAL finding or a failed git read into a blocking exit. ## Customization Edit the pattern lists in either script to add or modify detection patterns: - `CRITICAL_PATTERNS` / `$CriticalPatterns` - Review required - `HIGH_PATTERNS` / `$HighPatterns` - Review recommended ## Process 1. Gather the list of changed files (staged or explicit) 2. Run pattern matching against critical and high-risk file patterns 3. Report findings with risk level classification 4. Route to security agent if CRITICAL matches found ## Anti-Patterns | Avoid | Why | Instead | |-------|-----|---------| | Skipping detection before commits | Security files slip through unreviewed | Run detection on every commit with infrastructure changes | | Treating warnings as blocking | Scripts exit 0 intentionally | Use output to inform review decisions, not block commits | | Hardcoding custom patterns inline | Drifts from canonical pattern lists | Edit CRITICAL_PATTERNS/HIGH_PATTERNS in the scripts | | Ignoring HIGH-level matches | Potential security impact overlooked | Review HIGH matches, escalate to security agent when uncertain | | Running only one language script | May miss platform-specific detection | Use whichever script matches your environment | --- ## Verification After running security detection: - [ ] Script exited with code 0, or with 1 or 3 only under `--require-security-review` (blocked) - [ ] All CRITICAL matches reviewed - [ ] Security agent routed for CRITICAL findings - [ ] HIGH matches evaluated for review need - [ ] Output captured in session log if security-relevant --- ## Related Documents Backticked paths below are in the `rjmurillo/ai-agents` repository. They do not ship with this skill; a consumer install cannot resolve them. - `.project-toolkit/security/infrastructure-file-patterns.md`. Infrastructure file patterns. - `.project-toolkit/security/static-analysis-checklist.md`. Security agent capabilities. - `docs/orchestrator-routing-algorithm.md`. Orchestrator routing algorithm.