<p align="center">
<img src="codescan.svg" width="80" alt="codescan logo" />
</p>
<h1 align="center">codescan</h1>
<p align="center">
Fast, configurable code security scanner written in Rust.<br/>
Detects secrets, exploit patterns, weak crypto, and Unicode attacks across your entire codebase.
</p>
<p align="center">
<a href="README.zh.md">中文</a> ·
<a href="https://codescan.siiway.org">Docs</a> ·
<a href="https://github.com/siiway/codescan">GitHub</a> ·
<a href="https://crates.io/crates/codescan">crates.io</a>
</p>
---
## Features
- **Secret Detection** — hardcoded passwords, API keys, tokens, private keys, high-entropy strings (24+ rules)
- **Exploit Patterns** — SQL injection, XSS, command injection, path traversal, deserialization, prototype pollution, SSRF, and more (24 rules)
- **Cryptography Audits** — MD5, SHA1, DES, RC4, ECB mode, weak RSA, insecure random, missing TLS verification (11 rules)
- **Unicode Attacks** — Trojan Source (CVE-2021-42574) bidirectional control chars, zero-width chars, homoglyphs (3 rules)
- **Infrastructure** — hardcoded IPs, debug logging, plaintext HTTP URLs, security-relevant TODO comments (4 rules)
- **Custom Rules** — define your own rules in JSON using Rust `regex` syntax
- **Suppression** — inline comments (`codescan:ignore`) in any language, or config-file entries scoped by file/glob/line/rule/category/severity
- **Multiple Output Formats** — pretty (cargo-like), JSON (NDJSON), plain text
- **Parallel Scanning** — Rayon-powered parallel file processing, gitignore-aware traversal
- **Configurable** — TOML config file, severity overrides, rule disabling, size limits, and more
## Installation
**Linux / macOS:**
```bash
**Windows (PowerShell):**
```powershell
**Via cargo (crates.io):**
```bash
cargo install codescan
```
Pre-compiled binaries for Linux, macOS, and Windows are available on [GitHub Releases](https://github.com/siiway/codescan/releases/latest). See the [installation docs](https://codescan.siiway.org/guide/installation) for full details.
## Quick Start
```bash
# Scan current directory
codescan .
# Scan with exclusions
codescan --exclude "vendor/**" --exclude "node_modules/**" .
# Only report errors
codescan --severity error .
# Output as JSON
codescan --format json . > findings.jsonl
# List all rules
codescan --list-rules
```
## Example Output
```
error[SECRET001]: Hardcoded password
--> src/db/connection.py:14:12
|
= help: Use environment variables or a secrets manager instead
warning[CRYPTO001]: Weak hashing algorithm
--> src/auth/hash.py:8:5
|
= help: Use SHA-256 or better
found 1 error, 1 warning, 0 notes
```
## Configuration
Create `codescan.toml` in your project root:
```toml
[rules]
disabled = ["INFRA004"]
[rules.severity_overrides]
CRYPTO001 = "error"
[scanner]
max_file_size = 524288
[exclude]
paths = ["vendor/**", "node_modules/**", "dist/**"]
extensions = ["lock", "snap"]
[[suppress]]
file = "src/tests/fixtures/secrets.py"
rules = ["SECRET001", "SECRET002"]
reason = "Test fixture"
```
See the [full documentation](https://github.com/siiway/codescan) for all options.
## Suppression
Inline suppression works in any language:
```python
# codescan:ignore-next-line SECRET001
password = "test_only"
```
```javascript
const url = "http://internal.corp"; // codescan:ignore:INFRA004
```
```sql
-- codescan:ignore-next-line:INFRA001
INSERT INTO config VALUES ('host', '192.168.1.10');
```
Block suppression:
```python
# codescan:ignore-start SECRET001,SECRET002
TEST_PASSWORD = "test123"
TEST_API_KEY = "sk-test-abc123"
# codescan:ignore-end
```
## Custom Rules
```json
[
{
"id": "ORG001",
"category": "SECRET",
"severity": "error",
"pattern": "ACME_[A-Z0-9_]{16,}",
"message": "ACME internal token pattern detected",
"help": "Rotate and store in the secrets vault"
}
]
```
```bash
codescan --rules-file ./rules/org-rules.json .
```
## CI Integration
```yaml
# GitHub Actions
- name: Security scan
run: codescan --format text --fail-on error src/
```
Exit codes:
- `0` — no findings at or above `--fail-on` threshold
- `1` — one or more active (non-suppressed) findings meet the threshold
## CLI Reference
```
Usage: codescan [OPTIONS] [PATH]...
Arguments:
[PATH]... Paths to scan (default: .)
Options:
-i, --input <PATH> Additional input paths
-o, --output <FILE> Write output to file
-e, --exclude <GLOB> Exclude glob patterns
-c, --config <FILE> Config file [default: codescan.toml]
--severity <LEVEL> Minimum severity: error|warning|info [default: info]
--only-rules <IDS> Comma-separated rule IDs to check
--skip-rules <IDS> Comma-separated rule IDs to skip
-j, --threads <N> Parallel threads [default: CPU count]
--no-gitignore Disable .gitignore support
--hidden Scan hidden files
--max-filesize <BYTES> Max file size [default: 1048576]
-q, --quiet Suppress summary line
--fail-on <LEVEL> Exit 1 threshold [default: error]
--rules-file <FILE> Custom rules JSON file(s)
--show-suppressed Show suppressed findings
--list-rules List all rules and exit
-h, --help Print help
-V, --version Print version
```
## License
codescan is licensed under the [GNU General Public License v3.0](LICENSE).
Third-party Rust crate licenses are listed in [THIRD_PARTY_LICENSES/RUST_CRATES.md](THIRD_PARTY_LICENSES/RUST_CRATES.md).
Icon is from [microsoft/fluentui-system-icons](https://github.com/microsoft/fluentui-system-icons), licensed under MIT.
