Metadata-Version: 2.4
Name: secscanner
Version: 0.1.0
Summary: Enterprise-grade CLI security scanner with AI mode
Project-URL: Homepage, https://github.com/codescan-dev/codescan
Project-URL: Repository, https://github.com/codescan-dev/codescan
Project-URL: Bug Tracker, https://github.com/codescan-dev/codescan/issues
Project-URL: Changelog, https://github.com/codescan-dev/codescan/blob/main/CHANGELOG.md
Author: CodeScan Contributors
License: MIT License
        
        Copyright (c) 2025 CodeScan Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,sast,scanner,security,static-analysis,vulnerability
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40
Requires-Dist: chardet>=5.0
Requires-Dist: gitpython>=3.1
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.5
Requires-Dist: rich>=13.7
Requires-Dist: typer[all]>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install codescan

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

---

## Usage

### Scan a project

```bash
# 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

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

### Project stats (no scanning)

```bash
codescan stats ./myapp
```

### List all detection rules

```bash
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:

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

---

## Output Formats

### SARIF (GitHub Code Scanning)

```yaml
# .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

```bash
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](LICENSE).
