secscanner 0.1.0

Enterprise-grade CLI security scanner with AI mode

codescan

Enterprise-grade CLI security scanner — AST + regex + AI-powered.

Recursively walks a codebase, detects security vulnerabilities across 7 languages, builds attack chains, and renders everything in a rich terminal UI. Two modes: fully offline (regular) and Claude-enhanced (ai).

pip install codescan
codescan scan ./myproject

---

Features

Feature	Details
Languages	Python, JavaScript/TypeScript, Java, Go, PHP, Ruby, C/C++
Detection	AST analysis (Python) + regex (all languages) + secrets detection
Taint tracking	Traces user input → dangerous sink through variable assignments
Attack chains	Builds source → propagation → sink chains, including cross-file
AI mode	Claude enriches findings: true/false positive, CVSS, exploit steps, fix
Output formats	Terminal (Rich), JSON, HTML report, SARIF (GitHub Code Scanning)
Suppression	# nosec / # nosec: PY-CMD-001 inline comments
CI mode	--fail-on high exits with code 1 if threshold is breached
Incremental	--changed-only scans only git-modified files
Gitignore	Respects .gitignore when inside a git repository

---

Installation

pip install codescan

# For AI mode:
export ANTHROPIC_API_KEY=sk-ant-...

---

Usage

Scan a project

# Default: offline scan, medium+ severity, all languages
codescan scan ./myapp

# AI-enhanced scan
codescan scan ./myapp --mode ai

# Filter by language and severity
codescan scan ./myapp --lang python,javascript --severity high

# Save HTML report
codescan scan ./myapp --output html --save report.html

# Save SARIF for GitHub Code Scanning
codescan scan ./myapp --output sarif --save results.sarif

# CI mode — exit 1 on critical/high findings
codescan scan ./myapp --fail-on high

# Scan only git-changed files (fast in CI)
codescan scan ./myapp --changed-only

# Show code snippets for all findings
codescan scan ./myapp --verbose

Attack chain view for a single file

codescan chain ./app/views.py
codescan chain ./app/views.py --mode ai

Project stats (no scanning)

codescan stats ./myapp

List all detection rules

codescan rules
codescan rules --lang python --severity critical

---

CLI Options

codescan scan <path>

Option	Default	Description
--mode	regular	regular (offline) or ai (Claude-enhanced)
--lang	all	Language filter: python,js,java,go,php,ruby,c
--severity	medium	Minimum severity: low|medium|high|critical
--depth	unlimited	Max directory recursion depth
--output	terminal	Output format: terminal|json|html|sarif
--save	—	Save report to this file path
--model	claude-sonnet-4-20250514	Claude model (ai mode)
--threads	4	Parallel file analysis workers
--changed-only	off	Only scan git-modified files
--fail-on	—	Exit 1 if any finding ≥ this severity
--verbose	off	Show code snippets for all findings

---

Detection Rules

Python (AST-based — no false positives from comments/strings)

Rule	Severity	Description
PY-CMD-001	🔴 CRITICAL	subprocess with shell=True + dynamic arg
PY-EVAL-001	🔴 CRITICAL	eval()/exec() with non-constant argument
PY-SQLI-001	🔴 CRITICAL	String formatting inside .execute()
PY-DESER-001	🟠 HIGH	pickle/marshal/shelve deserialization
PY-DESER-002	🟠 HIGH	yaml.load() without SafeLoader
PY-PATH-001	🟠 HIGH	File path from user-controlled input
PY-SSRF-001	🟠 HIGH	HTTP request to user-controlled URL
PY-XXE-001	🟠 HIGH	Unsafe XML parser
PY-XSS-001	🟠 HIGH	Jinja2 with autoescape disabled
PY-LDAP-001	🟠 HIGH	LDAP search with tainted input
PY-SQLI-002	🟠 HIGH	% formatting in SQL variable name
PY-CRYPTO-001	🟡 MEDIUM	MD5/SHA-1 usage
PY-RAND-001	🟡 MEDIUM	random module for security
PY-FLASK-001	🟡 MEDIUM	app.run(debug=True)
PY-TMPFILE-001	🟡 MEDIUM	tempfile.mktemp()
PY-ASSERT-001	🔵 LOW	assert for security checks

JavaScript/TypeScript, Java, Go, PHP, Ruby, C

50+ additional rules covering SQL injection, command injection, XSS, SSRF, path traversal, deserialization, buffer overflows, format strings, and more.

Secrets Detection (all languages)

AWS keys, GitHub tokens, Anthropic/OpenAI API keys, Stripe keys, private key material, hardcoded passwords, database connection strings with embedded credentials.

---

AI Enhancement (--mode ai)

When ANTHROPIC_API_KEY is set and --mode ai is used, Claude enriches each finding with:

• True/false positive verdict with confidence score (0–100)
• Exploitability rating: low / medium / high / critical
• Attacker narrative: 3–5 sentences from attacker's perspective
• Step-by-step exploit: numbered exploitation guide
• Fix recommendation: explanation + code example
• CVSS estimate: e.g. 7.5 (CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N)
• Chain narrative: attack chain story for cross-file chains

Uses Anthropic prompt caching to minimise API costs on large codebases.

---

Suppression

Suppress a finding inline:

result = subprocess.run(cmd, shell=True)    # nosec: PY-CMD-001
data = yaml.load(stream)                    # nosec

---

Output Formats

SARIF (GitHub Code Scanning)

# .github/workflows/security.yml
- name: Security Scan
  run: codescan scan . --output sarif --save results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

HTML Report

codescan scan ./myapp --output html --save report.html

Generates a dark-themed self-contained HTML report with searchable findings table, attack chains, and AI annotations.

---

Architecture

codescan/
├── cli.py          — Typer CLI commands
├── walker.py       — File traversal, gitignore, encoding detection
├── analyzer.py     — Dispatch to AST (Python) or regex (others)
├── rules/
│   ├── python_ast.py  — AST visitor with taint tracking
│   ├── regex_rules.py — Regex rules for JS, Java, Go, PHP, Ruby, C
│   └── secrets.py     — Secrets detection with entropy analysis
├── chain.py        — Attack chain builder (source→propagation→sink graph)
├── ai_enhancer.py  — Claude integration with prompt caching
├── renderer.py     — Terminal (Rich), JSON, HTML, SARIF output
└── models.py       — Pydantic v2 data models

---

License

MIT — see LICENSE.