Imported from factory-ai/factory-plugins (plugins/security-engineer/skills/commit-security-scan/SKILL.md). Install upstream with npx skills add factory-ai/factory-plugins --skill commit-security-scan. Copyright stays with the author.

Commit Security Scan

Analyze code changes (commits, PRs, diffs) using LLM-powered reasoning to detect security vulnerabilities. This skill reads code directly and applies patterns from the repository's threat model to identify issues across all STRIDE categories.

When to Use This Skill

• PR review - Automated security scan on pull requests
• Pre-commit check - Scan staged changes before committing
• Branch comparison - Review security of feature branch changes
• Code review assistance - Help reviewers spot security issues

Prerequisites

This skill requires:

1. Threat model - .factory/threat-model.md must exist
2. Security config - .factory/security-config.json for severity thresholds

IMPORTANT: If these files don't exist, you MUST generate them first before proceeding with the security scan.

To generate the prerequisites:

1. Tell the user: "The threat model doesn't exist yet. I'll generate it first before scanning."
2. Run the threat-model-generation skill to create both files
3. Once complete, continue with the security scan

Do NOT ask the user to run the skill manually - just do it automatically as part of this workflow.

Inputs

The skill determines what to scan from the user's request:

If no scope is specified, prompt the user for clarification.

Instructions

Follow these steps in order:

Step 1: Verify Prerequisites (Auto-Generate if Missing)

Try to read these files:

• .factory/threat-model.md
• .factory/security-config.json

If either file is missing or cannot be read:

1. Inform the user: "The security threat model doesn't exist yet. I'll generate it first - this may take a minute."
2. Invoke the threat-model-generation skill to analyze the repository and create both files
3. Once generation completes, continue with Step 2

This ensures the security scan always has the threat model context it needs for accurate analysis.

Step 2: Get Changed Files

Based on the user's request, get the list of changed files and their diffs using git:

• For PRs: use gh pr diff
• For commits/ranges: use git diff or git show
• For staged changes: use git diff --cached

Read the full content of each changed file for context.

Step 3: Load Threat Model

Read .factory/threat-model.md and .factory/security-config.json to understand:

• The system's architecture and trust boundaries
• Known vulnerability patterns for this codebase
• Severity thresholds for findings

Step 4: Analyze for Vulnerabilities

For each changed file, systematically check for STRIDE threats:

S - Spoofing Identity

• Missing or weak authentication checks
• Session handling vulnerabilities
• Token/credential exposure in code
• Insecure cookie settings

T - Tampering with Data

• SQL Injection: String concatenation/interpolation in SQL queries
• Command Injection: User input in shell commands, eval(), exec()
• XSS: Unescaped user input in HTML/templates
• Mass Assignment: Blind assignment from request to model
• Path Traversal: User input in file paths without validation

R - Repudiation

• Missing audit logging for sensitive operations
• Insufficient error logging
• Log injection vulnerabilities

I - Information Disclosure

• IDOR: Direct object access without ownership verification
• Verbose error messages exposing internals
• Hardcoded secrets, API keys, credentials
• Sensitive data in logs or responses
• Debug endpoints exposed

D - Denial of Service

• Missing rate limiting on endpoints
• Unbounded resource consumption (file uploads, queries)
• Algorithmic complexity attacks (regex, sorting)
• Missing pagination on list endpoints

E - Elevation of Privilege

• Missing authorization checks on endpoints
• Role/permission bypass opportunities
• Privilege escalation through parameter manipulation

Step 5: Assess Each Finding

For each potential vulnerability:

1. Trace data flow: Follow user input from source to sink

   • Where does the input come from? (request params, body, headers, files)
   • Does it pass through validation/sanitization?
   • Where does it end up? (database, shell, response, file system)

2. Check for existing mitigations:

   • Is there validation elsewhere in the codebase?
   • Are there middleware/decorators that protect this code?
   • Does the framework provide automatic protection?

3. Determine severity:

   • CRITICAL: Remote code execution, auth bypass, data breach
   • HIGH: SQL injection, XSS, IDOR, privilege escalation
   • MEDIUM: Information disclosure, missing security headers
   • LOW: Best practice violations, minor issues

4. Assess confidence:

   • HIGH: Clear vulnerable pattern, direct data flow, no mitigations
   • MEDIUM: Possible vulnerability, some uncertainty about context
   • LOW: Suspicious pattern, likely has mitigations we can't see

Step 6: Generate Report

Create security-findings.json with this structure:

{
  "scan_id": "scan-YYYY-MM-DD-XXX",
  "scan_date": "<ISO 8601 timestamp>",
  "scan_type": "pr|commit|range|staged|working",
  "commit_range": "<base>..<head>",
  "pr_number": null,
  "threat_model_version": "<from security-config.json>",
  "findings": [
    {
      "id": "VULN-001",
      "severity": "HIGH",
      "stride_category": "Tampering",
      "vulnerability_type": "SQL Injection",
      "cwe": "CWE-89",
      "file": "src/api/users.py",
      "line_range": "45-49",
      "code_context": "<vulnerable code snippet>",
      "analysis": "<explanation of why this is vulnerable>",
      "exploit_scenario": "<how an attacker could exploit this>",
      "threat_model_reference": "Section 5.2 - SQL Injection",
      "existing_mitigations": [],
      "recommended_fix": "<how to fix the vulnerability>",
      "confidence": "HIGH",
      "reasoning": "<why this confidence level>"
    }
  ],
  "summary": {
    "total_findings": 0,
    "by_severity": { "CRITICAL": 0, "HIGH": 0, "MEDIUM": 0, "LOW": 0 },
    "by_stride": {
      "Spoofing": 0,
      "Tampering": 0,
      "Repudiation": 0,
      "InfoDisclosure": 0,
      "DoS": 0,
      "ElevationOfPrivilege": 0
    },
    "files_analyzed": 0
  }
}

Step 7: Report Results

1. Save findings to security-findings.json
2. Report summary to user (findings count by severity, triggered thresholds)
3. Check severity thresholds from security-config.json and note if any are triggered

CWE Reference

Common CWE mappings for findings:

Example Invocations

Scan a PR:

Scan PR #123 for security vulnerabilities

Scan staged changes before committing:

Scan my staged changes for security issues

Scan a feature branch:

Scan changes from main to feature/user-auth for vulnerabilities

Scan recent commits:

Scan the last 5 commits for security issues

References

• Analysis examples: analysis-examples.md (in this skill directory)
• Threat model: .factory/threat-model.md
• Security config: .factory/security-config.json
• OWASP Top 10
• CWE Top 25