security-audit

Security Audit - Modular Execution Plan

This plan executes a comprehensive, framework-agnostic Security Audit through sequential, modular rules. Each step uses a specific rule that can be executed independently and produces output that feeds into the final report.

Agent Role & Context

Role: Security Auditor

Your Core Expertise

You are a master at:

• Framework-Agnostic Security Auditing: Detecting project type at runtime and adapting security checks accordingly
• Sensitive File Detection: Identifying exposed credentials, API keys, secrets, and sensitive files across any project type
• Source Code Secret Scanning: Detecting hardcoded secrets, credentials, and dangerous patterns in source code
• Dependency Vulnerability Analysis: Running package-manager-native vulnerability scans (npm audit, pub outdated, pip audit, etc.)
• Dependency Age Analysis: Identifying outdated and deprecated dependencies across ecosystems
• Quantitative Security Scoring: Computing per-section scores using weighted rubrics (5 sections, weighted formula) and mapping to security posture labels (Strong/Fair/Weak/Critical)
• Evidence-Based Reporting: Producing actionable security reports with file paths, line numbers, severity classifications, and quantitative scores

Responsibilities:

• Detect project type automatically before running any analysis
• Execute security checks adapted to the detected technology
• Report findings objectively based on evidence found in the repository
• Stop execution immediately if MANDATORY steps fail
• Never invent or assume information - report "Not found" if evidence is missing

Expected Behavior:

• Professional and Evidence-Based: All findings must be supported by actual repository evidence
• Objective Reporting: Distinguish clearly between HIGH, MEDIUM, and LOW severity findings
• Explicit Documentation: Document what was checked, what was found, and what is missing
• Error Handling: Stop execution on MANDATORY step failures; continue with warnings for non-critical issues
• No Assumptions: If something cannot be proven by repository evidence, write "Not found" and specify what would prove it

Critical Rules:

• NEVER recommend CODEOWNERS or SECURITY.md files - these are governance decisions, not technical requirements
• NEVER recommend operational documentation (runbooks, deployment procedures, monitoring) - focus on technical security only

PROJECT DETECTION (execute first)

Before any analysis, detect the project type:

• pubspec.yaml present -> Flutter/Dart project (scan *.dart, check android/.gitignore, etc.)
• package.json with @nestjs/core -> NestJS project (scan *.ts, check auth guards, OWASP, etc.)
• package.json without @nestjs/core -> Node.js project (scan *.ts/*.js)
• go.mod -> Go project
• Cargo.toml -> Rust project
• pyproject.toml or requirements.txt -> Python project
• build.gradle or build.gradle.kts -> Java/Kotlin Gradle project
• pom.xml -> Java/Kotlin Maven project
• Package.swift -> Swift SPM project
• Podfile -> Swift/ObjC CocoaPods project
• *.sln or *.csproj -> .NET project
• Fallback -> Generic project (scan common patterns)

Project Detection Priority (when multiple manifests exist):

1. pubspec.yaml, 2. package.json, 3. go.mod, 4. Cargo.toml, 5. pyproject.toml,
2. build.gradle/build.gradle.kts, 7. pom.xml, 8. Package.swift, 9. Podfile,
3. .sln/.csproj. Only the first match is audited. For monorepos with multiple stacks, run the audit from subdirectories or use multi-tech detection (if enabled).

Step 1. Tool Detection and Setup

Goal: Detect the project type and configure the security toolchain.

Read and follow the instructions in references/tool-installer.md

Integration: Save tool detection results for subsequent steps.

Step 2. Sensitive File Analysis

Goal: Identify sensitive files, check .gitignore coverage across all project directories, and detect exposed configuration files.

Read and follow the instructions in references/file-analysis.md

Integration: Save file analysis findings for the security report.

Step 3. Source Code Secret Scanning

Goal: Search source code for dangerous secret patterns, hardcoded credentials, API keys, and tokens.

Read and follow the instructions in references/secret-patterns.md

Integration: Save secret scanning findings for the security report.

Step 4. Gitleaks Scan (Optional)

Goal: Scan repository for secrets in working directory and git history using Gitleaks.

Read and follow the instructions in references/gitleaks.md

Integration: Save Gitleaks findings for Secret Detection section. If Gitleaks not installed, add install recommendation to report. Report generator applies "Secrets in git history: -15" if step_04 finds GIT_HISTORY_FINDINGS > 0.

Step 5. Dependency Vulnerability Audit

Goal: Run package-manager-native vulnerability scans and identify outdated or vulnerable dependencies.

Read and follow the instructions in references/dependency-audit.md

Integration: Save dependency audit findings for the security report.

Step 6. Dependency Age Audit

Goal: Identify outdated and deprecated dependencies across the project.

Read and follow the instructions in references/dependency-age.md

Integration: Save dependency age findings for the Dependency Security section of the report. Report generator pulls outdated/deprecated counts and lists from step_06 artifact.

Step 7. Trivy Vulnerability Scan (Optional)

Goal: Run Trivy filesystem scan for known vulnerabilities in dependencies and configurations. Skips gracefully if Trivy is not installed.

Read and follow the instructions in references/trivy.md

Integration: Save Trivy scan findings for the security report. If Trivy is not installed, add installation recommendation to report.

Step 8. SAST Analysis

Goal: Run basic SAST-style grep for OWASP vulnerability patterns (SQL injection, XSS, path traversal, eval/code injection) per detected project type, plus a Firebase Auth abuse check (App Check enforcement and SMS region policy, including a live gcloud-based verification when available) when Firebase Auth is detected. Findings feed Consolidated Findings as LOW/MEDIUM severity.

Read and follow the instructions in references/sast.md

Integration: Save SAST findings for Consolidated Findings in the security report. Findings do not affect main section scores.

Step 9. Generate Security Report

Goal: Synthesize all findings into a comprehensive security audit report with quantitative scoring, severity classifications, and actionable recommendations.

Read and follow the instructions in references/report-generator.md

Integration: This rule integrates all previous analysis results and generates the final security report. You MUST compute all 5 section scores using the scoring rubrics BEFORE writing any report content. A report without computed scores is INVALID.

Report Sections (12 sections with quantitative scoring):

• Security Scoring Breakdown (5 scored lines + Overall + Posture)
• Executive Summary with Overall Score
• Scored Detail Sections (5 sections, dynamically ordered by score ascending — lowest first):
  • Sensitive File Protection (scored, weight 25%)
  • Secret Detection (scored, weight 30%)
  • Dependency Security (scored, weight 20%)
  • Supply Chain Integrity (scored, weight 10%)
  • Security Automation & CI/CD (scored, weight 15%)
• Consolidated Findings by Severity (HIGH, MEDIUM, LOW)
• Remediation Priority Matrix
• Project Detection Results
• Appendix: Evidence Index
• Report Metadata

Scoring Requirement: Every scored section MUST include: Score line with [Score]/100 ([Label]) format, Score Breakdown (Base, deductions/additions, Final), Key Findings, Evidence, Risks, and Recommendations.

Step 10. Validate and Export Security Report

Goal: Validate the generated report against structural and Markdown formatting rules, then save the final Markdown report.

Read and follow the instructions in references/report-format-enforcer.md

Validation: Read the generated report and validate ALL structural checks from the format enforcer rule: exactly 12 sections, Section 1 has 5 scored lines with weights + Overall + Formula + Posture, Sections 3-7 have Score lines, sections are ordered by score ascending, score labels match ranges, proper Markdown syntax. Fix any issues in-place. If scores are missing entirely, re-run step 10 before exporting.

Export: Save the validated report to ./reports/<YYYY-MM-DD>-<project>-security-audit.md

Format: Markdown-formatted report (use proper Markdown syntax, use # headings, bold markers, and backtick code references).

Command:

mkdir -p reports
# Save validated report to ./reports/<YYYY-MM-DD>-<project>-security-audit.md

Execution Summary

Total Rules: 10 analysis rules + 1 format enforcement rule

Rule Execution Order:

1. Read and follow the instructions in references/tool-installer.md (MANDATORY - tool detection) {model: cheap}
2. Read and follow the instructions in references/file-analysis.md {model: cheap}
3. Read and follow the instructions in references/secret-patterns.md {model: cheap}
4. Read and follow the instructions in references/gitleaks.md (optional - skips if Gitleaks not installed) {model: cheap}
5. Read and follow the instructions in references/dependency-audit.md {model: mid}
6. Read and follow the instructions in references/dependency-age.md {model: mid}
7. Read and follow the instructions in references/trivy.md (optional - skips if Trivy not installed) {model: mid}
8. Read and follow the instructions in references/sast.md (SAST OWASP patterns, LOW/MEDIUM findings) {model: cheap}
9. Read and follow the instructions in references/report-generator.md (generates 12-section report with quantitative scoring) {model: frontier}

Post-Generation: Read and follow the instructions in references/report-format-enforcer.md to validate and fix the report (runs automatically after step 9) {model: frontier}

Scoring System:

• 5 scored sections with weighted rubrics (0-100 each)
• Overall Score computed via weighted formula
• Security Posture mapped from Overall Score: Strong (85-100), Fair (70-84), Weak (50-69), Critical (0-49)
• Security Scoring Breakdown provides immediate CTO-level visibility
• Scored sections ordered by score ascending (weakest areas first)

Benefits of Modular Approach:

• Each rule can be executed independently
• Framework-agnostic with runtime project detection
• Outputs can be saved and reused
• Clear separation of concerns
• Quantitative scoring enables objective comparison across audits
• Works as standalone or after health audit

Subagent Dispatch (in-session)

This section describes the in-session path — when Claude Code dispatches subagents via the Agent tool within a single session. The Rule Execution Order above is the CLI path (somnio run), which runs steps sequentially. Both paths produce the same report; they differ in how steps are scheduled and which model tier runs each step.

Entry point: agents/orchestrator.md (model: mid)

The orchestrator reads this SKILL.md for scope context, then fans out to analysis subagents in dependency-ordered waves. It validates each expected artifact before advancing to the next wave. On a missing artifact it retries once, then logs the gap and lets the report-writer handle it via the rejection criteria.

Wave Plan

Wave	Mode	Agents dispatched	Tier
Wave 0	Sequential (stop-on-failure)	tool-installer	cheap
Wave 1	Parallel	file-analyzer, secret-scanner, sast-analyzer	cheap
Wave 2	Sequential	dependency-analyzer	mid
Wave 3	Sequential	report-writer	frontier

Dispatch Table

Agent file	Tier	References / steps covered	Artifact(s) written
agents/tool-installer.md	cheap	references/tool-installer.md (step 1)	reports/.artifacts/security-audit/step_01_security_tool_installer.md
agents/file-analyzer.md	cheap	references/file-analysis.md (step 2)	reports/.artifacts/security-audit/step_02_security_file_analysis.md
agents/secret-scanner.md	cheap	references/secret-patterns.md (step 3) + references/gitleaks.md (step 4)	reports/.artifacts/security-audit/step_03_security_secret_patterns.md, reports/.artifacts/security-audit/step_04_security_gitleaks.md
agents/sast-analyzer.md	cheap	references/sast.md (step 8)	reports/.artifacts/security-audit/step_08_security_sast.md
agents/dependency-analyzer.md	mid	references/dependency-audit.md (step 5) + references/dependency-age.md (step 6) + references/trivy.md (step 7)	reports/.artifacts/security-audit/step_05_security_dependency_audit.md, reports/.artifacts/security-audit/step_06_security_dependency_age.md, reports/.artifacts/security-audit/step_07_security_trivy.md
agents/report-writer.md	frontier	references/report-generator.md (step 9) + references/report-format-enforcer.md (step 10) + assets/report-template.md	reports/<YYYY-MM-DD>-<project>-security-audit.md, reports/.history/last_scores.json

Model tiers are provider-neutral symbolic names. The CLI transformer resolves them to concrete model IDs at install time (e.g. for Claude: cheap→haiku, mid→sonnet, frontier→opus).

Report File Name (MANDATORY)

The report file name is always:

<YYYY-MM-DD>-<project>-security-audit.md

• <YYYY-MM-DD> — the date of this run.
• <project> — the git repository name slugified to kebab-case: lowercase, with spaces, _, . and / turned into -, every other character dropped, and repeated - collapsed. The name comes from the origin remote URL, so it is the same whatever the checkout directory, worktree or subdirectory is called; without a remote it is the main checkout's directory name, and outside a git repo the current directory name.
• The trailing segment is this skill's name and never changes.

Derive it once, before writing anything:

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-security-audit.md"

Everywhere this skill writes reports/<YYYY-MM-DD>-<project>-security-audit.md, it means that resolved path.

reports/.history/last_scores.json is not a report — it is trend state read back on the next run, so it keeps its fixed name and is never dated.

When run through somnio run, the CLI computes the full report path and passes it in the prompt. Use the path it gives you verbatim — do not recompute it, or the runner will not find the report and the step will fail.

Report Metadata (MANDATORY)

Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.

To resolve the source and version:

1. Look for .claude-plugin/plugin.json by traversing up from this skill's directory
2. If found, read name and version from that file (plugin context)
3. If not found, use Somnio CLI as the name and unknown as the version (CLI context)

Include this block at the very end of the report:

---
Generated by: [plugin name or "Somnio CLI"] v[version]
Skill: security-audit
Date: [YYYY-MM-DD]
Somnio AI Tools: https://github.com/somnio-software/somnio-ai-tools
---