security-detection

Triggers

| Trigger Phrase | Operation | |----------------|-----------| | scan for security changes | detect-infrastructure with staged files | | check security-critical files | detect-infrastructure with file list | | run security scan on changes | 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

# 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

When security-critical files are detected:

=== 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:
  Task(subagent_type="security", prompt="Review infrastructure changes")

When no matches:

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:

# Security detection (non-blocking warning)
python3 .claude/skills/security-detection/detect_infrastructure.py --use-git-staged

CI Integration

On a Linux pull-request runner, pass the changed paths explicitly. CI checkouts do not have a staged diff.

- 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"
    | python .claude/skills/security-detection/detect_infrastructure.py
    --files-from-stdin

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success (warning shown if matches found, non-blocking) |

The scripts are designed to be non-blocking warnings. They always exit 0 to avoid blocking commits or CI. The warning is informational only.

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 (non-blocking)
• [ ] 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.

• .agents/security/infrastructure-file-patterns.md. Infrastructure file patterns.
• .agents/security/static-analysis-checklist.md. Security agent capabilities.
• docs/orchestrator-routing-algorithm.md. Orchestrator routing algorithm.

<!-- vendor-portability: declared. This skill cites .agents/security/infrastructure-file-patterns.md, .agents/security/static-analysis-checklist.md, and docs/orchestrator-routing-algorithm.md as background reading. All three are citations only; the detection patterns documented here are self-contained, so a vendored install loses the further reading, not the capability. Issue #2050. -->