---
roadcrew_template_name: "audit-security.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# audit-security

Automatically identify security vulnerabilities, authentication issues, and data safety concerns in your codebase.

## Usage

```bash
/audit-security [--severity critical|high|medium|low] [--files pattern]
```

## What This Command Does

Performs comprehensive security analysis including:
- **Vulnerability Detection** - SQL injection, XSS, CSRF, insecure deserialization
- **Authentication Audit** - Missing auth checks, weak auth patterns, exposed credentials
- **Data Safety** - Unencrypted sensitive data, PII exposure, insecure logging
- **Dependency Scanning** - Known vulnerabilities in npm/pip packages
- **Compliance Issues** - OWASP Top 10, industry standards violations

Generates security report with severity levels and remediation guidance.

## Implementation Strategy

### Phase 1: Setup & Integration

1. **Detect project type** from tech-stack.md (TypeScript/Node.js, Python, Go, etc.)

2. **Select security tools** based on project type:
   - **TypeScript/Node.js**: ESLint security plugins, npm audit, semgrep
   - **Python**: Bandit, safety, semgrep
   - **Go**: gosec, staticcheck

3. **Initialize scanning context**:
   - Read codebase structure
   - Load existing security configurations (ESLint, bandit configs)
   - Determine baseline (create baseline if first run)

### Phase 2: Scan & Analysis

1. **Run security scanners** (parallel execution):
   ```typescript
   // Pseudo-code pattern
   const eslintResults = runESLintWithSecurityPlugins();
   const auditResults = runNpmAudit();
   const semgrepResults = runSemgrep();
   const authIssues = analyzeAuthPatterns();
   const dataIssues = analyzeDataHandling();
   ```

2. **Analyze authentication patterns**:
   - Identify unprotected endpoints/routes
   - Check auth middleware presence
   - Flag weak auth schemes (basic auth, single-factor)
   - Verify CORS and CSRF protections

3. **Analyze data handling**:
   - Detect sensitive data in logs
   - Check encryption usage
   - Identify unvalidated user input
   - Find insecure data transmission

4. **Prioritize by severity**:
   - **🔴 CRITICAL**: RCE, SQL injection, auth bypass, exposed secrets
   - **🟠 HIGH**: XSS, CSRF, unencrypted PII, weak auth
   - **🟡 MEDIUM**: Insecure defaults, missing rate limiting, weak crypto
   - **🟢 LOW**: Best practices, code hygiene, performance

### Phase 3: Report Generation

Generate structured report:

```markdown
# Security Audit Report

**Scan Date**: {{DATE}}
**Project**: {{PROJECT_NAME}}
**Severity Filter**: {{SEVERITY_FILTER}}

## Summary

- 🔴 Critical Issues: N
- 🟠 High Issues: N  
- 🟡 Medium Issues: N
- 🟢 Low Issues: N
- ✅ Total Findings: N

## Findings by Category

### 🚨 Authentication & Authorization (N issues)

**Finding 1: [Title]**
- **Severity**: 🔴 CRITICAL / 🟠 HIGH / 🟡 MEDIUM / 🟢 LOW
- **Location**: `path/to/file.ts:123`
- **Issue**: [Description]
- **Risk**: [What could go wrong]
- **Remediation**: [How to fix]
- **CWE**: [CWE-XXX link]
- **OWASP**: [A01:2021 – Broken Access Control]

### 🔐 Data & Encryption (N issues)

[Similar format]

### 💉 Injection Vulnerabilities (N issues)

[Similar format]

### 📦 Dependency Vulnerabilities (N issues)

[Similar format]

### ⚙️ Configuration Issues (N issues)

[Similar format]

## Improvement Priority

### Phase 1 (Critical - Fix Immediately)
- [Critical finding 1]
- [Critical finding 2]

### Phase 2 (High - Fix This Sprint)
- [High finding 1]
- [High finding 2]

### Phase 3 (Medium - Plan for Next Release)
- [Medium finding 1]

### Phase 4 (Low - Backlog)
- [Low finding 1]

## Metrics & Trends

- Previous scan: {{PREV_DATE}} (N findings)
- Current scan: {{DATE}} (N findings)
- Trend: 📈 Increased / 📉 Decreased / ➡️ Stable
- Velocity: {{N}} issues resolved since last scan

## Next Steps

1. **Review** findings with security engineer
2. **Triage** each finding (fix now / accept risk / false positive)
3. **Create** GitHub issues for high-severity findings
4. **Track** remediation progress
5. **Rescan** after fixes deployed
```

### Phase 4: Integration Points

1. **GitHub Issues Integration**:
   - Create issue for each critical/high finding
   - Add `security` and severity labels
   - Link to security documentation

2. **CI/CD Integration**:
   - Fail build if critical findings > threshold
   - Block deploy if high findings unreviewed
   - Generate SARIF report for GitHub Security tab

3. **Continuous Monitoring**:
   - Baseline from initial scan
   - Track trends over time
   - Alert on regressions
   - Measure remediation velocity

## Acceptance Criteria

- ✅ Command runs without errors
- ✅ Detects common vulnerabilities (SQL injection, XSS, CSRF)
- ✅ Identifies auth and authorization issues
- ✅ Flags data exposure and privacy concerns
- ✅ Provides severity levels (critical → low)
- ✅ Generates clear remediation recommendations
- ✅ Supports --severity flag for filtering
- ✅ Supports --files pattern for targeted scanning
- ✅ Generates report in markdown + JSON formats
- ✅ Can create GitHub issues from critical findings

## Output Format Example

```bash
$ /audit-security --severity high

🔐 Security Audit: roadcrew-internal

Scan Time: 2.3 seconds | Files Scanned: 147 | Severity: high+

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 FINDINGS SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 Critical: 2
🟠 High: 5
🟡 Medium: 12
🟢 Low: 8

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚨 CRITICAL FINDINGS (Fix Immediately)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Finding 1]
Location: scripts/utils/db.ts:45
Issue: SQL injection vulnerability in query construction
Remediation: Use parameterized queries / prepared statements
Reference: CWE-89 (https://cwe.mitre.org/data/definitions/89.html)

[Finding 2]
...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟠 HIGH FINDINGS (Fix This Sprint)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[5 high findings...]

📊 Full report: config/reports/security-audit-2025-10-29.md
📋 JSON format: config/reports/security-audit-2025-10-29.json

🔗 Create GitHub issues from critical findings?
   Run: npm run audit-security -- --create-issues
```

## Files Generated

- `config/reports/security-audit-{{DATE}}.md` - Full report
- `config/reports/security-audit-{{DATE}}.json` - Machine-readable format
- `config/reports/security-baseline.json` - Baseline for comparison
- Optional: GitHub issues with `security-critical` / `security-high` labels

## When to Run

- **Before deployment** - Security gate check
- **Weekly** - Continuous monitoring
- **After dependency updates** - Verify no new vulnerabilities
- **On code review** - Automated scanning in CI/CD
- **Quarterly** - Security audit and trend analysis

## Flags & Options

```bash
--severity critical|high|medium|low     # Minimum severity to report (default: high)
--files pattern                         # Scan specific files only (glob pattern)
--create-issues                         # Auto-create GitHub issues for critical findings
--baseline                              # Use/create security baseline
--compare previous                      # Compare to previous scan
--fail-on critical|high                 # Fail with exit code 1 if issues found
--json                                  # Output JSON only (no markdown)
```