Cybersecurity Audit Skill

A Claude Agent skill that performs hybrid source code security audits — deterministic pattern scanning, SAST tool integration (semgrep/bandit/snyk/trivy), LLM contextual analysis, and architecture-level finding detection. Produces Markdown and JSON reports with optional auto-fix capability.

Includes intentionally vulnerable demo apps (Flask, Node.js, Go, React) to demonstrate the audit capability live.

Choose your environment below. Step 2 (SAST tools) and Step 3 (output directory) are the same for both.

Claude Code uses CLAUDE.md for persistent instructions and .claude/skills/ for reusable slash-command workflows.

Step A1 — Install as a global skill (available in any project)

# Create the global skills directory
mkdir -p ~/.claude/skills/cybersecurity-audit

# Copy the skill file
cp SKILL.md ~/.claude/skills/cybersecurity-audit/SKILL.md

Invoke it in any Claude Code session with:

/cybersecurity-audit

Step A2 — Or install as a project-level skill (scoped to this repo)

# Run from inside the cloned repo
mkdir -p .claude/skills/cybersecurity-audit
cp SKILL.md .claude/skills/cybersecurity-audit/SKILL.md

Invoke it the same way:

/cybersecurity-audit

Step A3 — Or inject via CLAUDE.md (no slash command needed)

If you prefer the skill to load automatically for every session in this repo, append it to your project's CLAUDE.md:

cat SKILL.md >> CLAUDE.md

Or create a user-level CLAUDE.md so the skill is always available globally:

cat SKILL.md >> ~/.claude/CLAUDE.md

Verify it's loaded:

# Inside the repo, start a Claude Code session and run:
/claude
# Then type /cybersecurity-audit — it should appear in autocomplete

Hermes uses a ~/.hermes/skills/ directory with category subdirectories.

Step B1 — Copy the skill into Hermes

# Create the skill directory
mkdir -p ~/.hermes/skills/security/cybersecurity-audit

# Copy the skill file
cp SKILL.md ~/.hermes/skills/security/cybersecurity-audit/SKILL.md

# Copy reference files (optional but recommended)
mkdir -p ~/.hermes/skills/security/cybersecurity-audit/references
cp INSTALL.md ~/.hermes/skills/security/cybersecurity-audit/references/tool-install-guide.md
cp templates/findings-schema.json ~/.hermes/skills/security/cybersecurity-audit/references/

Step B2 — Verify the skill is visible

In your Hermes session:

/skills

You should see cybersecurity-audit listed. Hermes auto-loads the skill when you use trigger phrases like "audit this app", "run a security scan", or "find vulnerabilities".

See INSTALL.md for full platform-specific instructions (Linux, macOS, cloud VMs).

Quick install:

pip install bandit semgrep njsscan pip-audit
npm install -g eslint eslint-plugin-security

If bandit or semgrep are not found after install, add the pip bin directory to PATH:

export PATH=$PATH:~/.local/bin
# Make it permanent:
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc && source ~/.bashrc

cd cybersec-audit-skill
mkdir -p .audit
# .audit/ is already in .gitignore in this repo

# In your Claude Code or Hermes session:
"Audit the vulnerable-demo/flask-app directory"

# The agent will:
# 1. Map the codebase (languages, frameworks, entry points)
# 2. Run deterministic grep-based pattern scanners (Layer 1)
# 3. Run semgrep/bandit/snyk/trivy if available (Layer 2)
# 4. Detect architecture-level / multi-file gaps (Step 3b)
# 5. Perform LLM contextual analysis on data flows (Layer 3)
# 6. Calculate risk score (0–100) with severity breakdown
# 7. Generate structured report (Markdown + JSON)
# 8. Offer to auto-fix findings (after your approval)

├── SKILL.md                                  # Agent skill — load this
├── INSTALL.md                                # SAST tool installation guide
├── README.md                                 # This file
├── docs/
│   └── risk-scoring.md                       # Risk scoring methodology
├── ci/
│   ├── layer0_dependency_audit.py            # Dependency audit CI script
│   ├── entropy_scan.py                       # Entropy-based secrets scanner
│   └── check_findings.py                     # CI gate — blocks on CRITICAL/HIGH
├── templates/
│   ├── report-template.md                    # Markdown report template
│   └── findings-schema.json                  # JSON findings schema
├── vulnerable-demo/
│   ├── flask-app/
│   │   ├── app.py                            # Flask — SQLi, cmd inj, XSS, path traversal
│   │   ├── config.py                         # Hardcoded secrets, DEBUG=True
│   │   ├── utils.py                          # Weak crypto, pickle deserialization
│   │   ├── requirements.txt
│   │   └── tests/
│   │       └── security_regression.py        # 20-test regression harness
│   ├── node-app/
│   │   ├── server.js                         # Express — SQLi, eval, SSRF, IDOR
│   │   └── package.json
│   ├── go-app/
│   │   ├── main.go                           # Go — SQLi, cmd inj, SSRF, weak crypto
│   │   └── go.mod
│   └── react-app/
│       └── src/
│           └── App.js                        # React — XSS, localStorage secrets, exposed keys
└── .github/
    └── workflows/
        └── security-audit.yml                # CI/CD security gate workflow

The .github/workflows/security-audit.yml workflow runs on every PR and provides:

• Layer 0 dependency audit (ci/layer0_dependency_audit.py) — pip-audit, npm audit, trivy, license scanning
• Entropy-based secrets detection (ci/entropy_scan.py) — Shannon entropy scanning + git history scan
• CI gate (ci/check_findings.py) — blocks merge on CRITICAL or HIGH findings

Run locally:

python ci/layer0_dependency_audit.py /path/to/project
python ci/entropy_scan.py /path/to/project
python ci/check_findings.py .audit/findings-latest.json

Risk scores use a weighted formula capped at 100:

score = min((CRITICAL × 25) + (HIGH × 10) + (MEDIUM × 3) + (LOW × 1), 100)

See docs/risk-scoring.md for full methodology including architecture-level findings and delta scoring.

MIT — see LICENSE for full text.