Metadata-Version: 2.4
Name: forj-shieldscan
Version: 0.1.0
Summary: Scan your code for security issues in 30 seconds
Author-email: ShieldScan <hello@shieldscan.io>
License-Expression: MIT
Project-URL: Homepage, https://shieldscan.io
Project-URL: Repository, https://github.com/FORJ-AI/shieldscan-oss
Project-URL: Issues, https://github.com/FORJ-AI/shieldscan-oss/issues
Project-URL: Changelog, https://github.com/FORJ-AI/shieldscan-oss/blob/main/CHANGELOG.md
Keywords: security,scanner,sast,code-review,secrets,vulnerabilities,ci-cd,github-actions
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <h1 align="center">🛡️ ShieldScan</h1>
  <p align="center"><strong>Scan your code for security issues in 30 seconds.</strong></p>
  <p align="center">
    <a href="#quick-start">Quick Start</a> •
    <a href="#what-it-finds">What It Finds</a> •
    <a href="#add-to-ci">Add to CI</a> •
    <a href="#output-formats">Output Formats</a> •
    <a href="#pro-features">Pro Features</a>
  </p>
</p>

<p align="center">
  <img src="https://img.shields.io/pypi/v/shieldscan?color=00e676&label=version" alt="Version">
  <img src="https://img.shields.io/badge/python-3.9+-blue" alt="Python">
  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Dependencies">
  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
  <img src="https://img.shields.io/badge/rules-40-orange" alt="Rules">
</p>

---

ShieldScan finds hardcoded secrets, SQL injection, XSS, command injection, and 35+ other security issues in your code. Zero config. Zero dependencies. Just run it.

## Quick Start

```bash
pip install shieldscan
shieldscan scan .
```

That's it. You'll see something like:

```
🛡️ ShieldScan v0.1.0

Scanning 142 files...

🔴 CRITICAL: Hardcoded AWS Access Key
   src/config.py:42 — AKIA... pattern detected
   CWE-798 | Fix: Move to environment variable

🟠 HIGH: SQL String Concatenation
   src/db.py:89 — f-string in SQL query
   CWE-89 | Fix: Use parameterized queries

🟡 MEDIUM: Debug Mode Enabled in Production
   src/settings.py:12 — DEBUG = True
   CWE-489 | Fix: Set DEBUG = False in production

Score: C (3 issues found)
```

## How It Works

```mermaid
flowchart TD
    A["📁 Your Code"] --> B["🔍 ShieldScan CLI"]
    B --> C{"40 Security Rules"}
    C --> D["🔑 Secrets Detection\n10 rules"]
    C --> E["💉 Injection Patterns\n8 rules"]
    C --> F["⚙️ Config Issues\n6 rules"]
    C --> G["📦 Vulnerable Deps\n5 rules"]
    C --> H["🔐 Crypto Weaknesses\n4 rules"]
    C --> I["🔓 Auth Issues\n3 rules"]
    C --> J["📄 File Checks\n4 rules"]
    
    D & E & F & G & H & I & J --> K{"Findings"}
    
    K -->|"Text"| L["🖥️ Terminal Output\nColored, graded A-F"]
    K -->|"JSON"| M["📋 Structured JSON\nFor automation"]
    K -->|"SARIF"| N["🐙 GitHub Code Scanning\nNative integration"]
    K -->|"Markdown"| O["💬 PR Comments\nBranded reports"]
    
    style A fill:#1a1a2e,stroke:#00e676,color:#fff
    style B fill:#16213e,stroke:#00e676,color:#fff
    style C fill:#0f3460,stroke:#00e676,color:#fff
    style K fill:#0f3460,stroke:#00e676,color:#fff
    style L fill:#1a1a2e,stroke:#00e676,color:#fff
    style M fill:#1a1a2e,stroke:#00e676,color:#fff
    style N fill:#1a1a2e,stroke:#00e676,color:#fff
    style O fill:#1a1a2e,stroke:#00e676,color:#fff
```

## What It Finds

| Category | Rules | Examples |
|----------|-------|---------|
| 🔑 **Secrets** | 10 | AWS keys (`AKIA...`), GitHub tokens, Stripe keys, JWTs, private keys, generic API keys/passwords |
| 💉 **Injection** | 8 | SQL injection (f-strings, concatenation), command injection (`os.system`, `subprocess`), XSS (`innerHTML`, `dangerouslySetInnerHTML`), XXE |
| ⚙️ **Config** | 6 | Debug mode in production, CORS wildcard, SSL verification disabled, insecure cookies |
| 📦 **Dependencies** | 5 | Known vulnerable versions of lodash, axios, Django, Flask, jsonwebtoken |
| 🔐 **Crypto** | 4 | Weak hashing (MD5, SHA1), insecure random (`Math.random` for tokens), hardcoded IVs |
| 🔓 **Auth** | 3 | Hardcoded credentials, weak session config, `eval`/`exec` with dynamic input |
| 📄 **Files** | 4 | `.env` files committed, private key files, `pickle.loads`, `yaml.load` without SafeLoader |

## Scan Pipeline

```mermaid
flowchart LR
    subgraph Input
        A["Developer runs\nshieldscan scan ."]
    end
    
    subgraph Scanner["🛡️ ShieldScan Engine"]
        B["Collect Files\n.py .js .ts .env\nDockerfile etc."] 
        C["Pattern Matching\n40 regex rules\nper file, per line"]
        D["False Positive\nSuppression\nskip tests, comments"]
        E["Severity Scoring\nCritical → Low\nCWE mapping"]
    end
    
    subgraph Output
        F["Grade: A+ to F\nExit code 0 or 1"]
    end
    
    A --> B --> C --> D --> E --> F
    
    style Scanner fill:#0d1117,stroke:#00e676,color:#fff
```

## Add to CI

### GitHub Actions (30 seconds)

Copy this to `.github/workflows/shieldscan.yml`:

```yaml
name: Security Scan
on: [pull_request]
jobs:
  shieldscan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install shieldscan
      - run: shieldscan scan . --format sarif > results.sarif
        continue-on-error: true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
        if: always()
```

This gives you **native GitHub Code Scanning** — findings appear directly in your PR diff:

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant SS as ShieldScan
    
    Dev->>GH: Opens Pull Request
    GH->>SS: Triggers scan workflow
    SS->>SS: Scans changed files
    SS->>GH: Uploads SARIF results
    GH->>Dev: Shows findings in PR diff
    
    Note over Dev,GH: Findings appear inline<br/>with fix suggestions
```

### Other CI Systems

```bash
# GitLab CI
shieldscan scan . --format json > shieldscan-report.json

# Jenkins
shieldscan scan . --severity high  # Exit code 1 on high+ findings

# Pre-commit hook
shieldscan scan . --severity critical  # Block commits with critical issues
```

## Output Formats

### Terminal (default)
```bash
shieldscan scan .
```
Colored output with severity badges, file locations, fix suggestions, and an overall grade (A+ to F).

### JSON
```bash
shieldscan scan . --format json
```
```json
[
  {
    "severity": "critical",
    "title": "Hardcoded AWS Access Key",
    "file": "src/config.py",
    "line": 42,
    "cwe": "CWE-798",
    "fix": "Move to environment variable"
  }
]
```

### SARIF (GitHub Code Scanning)
```bash
shieldscan scan . --format sarif > results.sarif
```
SARIF 2.1.0 format compatible with GitHub Code Scanning, VS Code SARIF Viewer, and other security tools.

### Markdown (PR Comments)
```bash
shieldscan scan . --format markdown
```
Generates a branded security report ready to paste as a PR comment:

> ## 🛡️ ShieldScan Security Report
> **Score: B** (2 issues found)
> 
> ### 🔴 Critical (0) | 🟠 High (1) | 🟡 Medium (1) | 🔵 Low (0)
> 
> ---
> **🟠 HIGH: Hardcoded API Key** — `src/config.py:42`
> <details><summary>Fix</summary>Move to environment variable using os.getenv()</details>

## CLI Options

```
shieldscan scan <path>              # Scan a directory or file
shieldscan scan . --format json     # JSON output
shieldscan scan . --format sarif    # SARIF for GitHub Code Scanning
shieldscan scan . --format markdown # PR comment format
shieldscan scan . --severity high   # Only high+ severity
shieldscan scan . --exclude tests/  # Exclude directories
shieldscan version                  # Show version
```

| Flag | Description |
|------|-------------|
| `--format` | Output format: `text` (default), `json`, `sarif`, `markdown` |
| `--severity` | Minimum severity: `critical`, `high`, `medium`, `low` |
| `--exclude` | Directories to skip (comma-separated) |

**Exit codes:** `0` = clean, `1` = critical/high findings, `2` = error

## Python API

```python
from shieldscan import scan_directory, scan_file

# Scan a directory
findings = scan_directory("/path/to/project")
for f in findings:
    print(f"{f['severity']}: {f['title']} at {f['file']}:{f['line']}")

# Scan a single file
findings = scan_file("/path/to/file.py")
```

## Architecture

```mermaid
graph TB
    subgraph "ShieldScan CLI (Open Source)"
        CLI["shieldscan scan ."]
        Scanner["Scanner Engine\n40 Rules • Zero Deps"]
        Formatter["Output Formatter\nText • JSON • SARIF • MD"]
        CLI --> Scanner --> Formatter
    end
    
    subgraph "ShieldScan Pro (SaaS)"
        Dashboard["Web Dashboard\nTrend Graphs • Team View"]
        Live["Live Target Scanning\nSSL • Headers • OWASP"]
        Compliance["Compliance Reports\nSOC 2 • PCI • HIPAA"]
        AI["AI Remediation\nAuto-fix PRs"]
        GitApp["GitHub App\nAuto PR Comments"]
    end
    
    Scanner -.->|"Upgrade"| Dashboard
    
    style CLI fill:#0d1117,stroke:#00e676,color:#fff
    style Scanner fill:#0d1117,stroke:#00e676,color:#fff
    style Formatter fill:#0d1117,stroke:#00e676,color:#fff
    style Dashboard fill:#1a1a2e,stroke:#ffd700,color:#fff
    style Live fill:#1a1a2e,stroke:#ffd700,color:#fff
    style Compliance fill:#1a1a2e,stroke:#ffd700,color:#fff
    style AI fill:#1a1a2e,stroke:#ffd700,color:#fff
    style GitApp fill:#1a1a2e,stroke:#ffd700,color:#fff
```

## Pro Features

Need more? **[ShieldScan Pro](https://shieldscan.io)** adds:

| Feature | Free (CLI) | Pro ($49/mo) | Enterprise |
|---------|-----------|-------------|------------|
| Static code scanning | ✅ 40 rules | ✅ 100+ rules | ✅ Custom rules |
| CLI & CI integration | ✅ | ✅ | ✅ |
| GitHub Code Scanning | ✅ SARIF | ✅ GitHub App | ✅ GitHub App |
| Live website scanning | — | ✅ SSL, headers, OWASP | ✅ Full pentest |
| Compliance reports | — | ✅ SOC 2, PCI DSS | ✅ + HIPAA, ISO 27001 |
| AI remediation | — | ✅ Fix suggestions | ✅ Auto-fix PRs |
| Team dashboard | — | ✅ 5 repos | ✅ Unlimited |
| Shareable scorecards | — | ✅ | ✅ |
| Slack/Jira alerts | — | — | ✅ |
| SSO & RBAC | — | — | ✅ |

## Contributing

ShieldScan is open source (MIT). We welcome contributions!

1. Fork this repo
2. Add a new rule to `shieldscan/scanner.py`
3. Test it: `shieldscan scan . --format json`
4. Open a PR

### Adding a Rule

Rules are regex patterns in `scanner.py`. Each rule has:
- `id`: Unique identifier
- `pattern`: Compiled regex
- `severity`: critical / high / medium / low
- `title`: Human-readable name
- `cwe`: CWE reference
- `fix`: Remediation suggestion
- `languages`: Which file types to check

## License

MIT — see [LICENSE](LICENSE)

---

<p align="center">
  Made with 🛡️ by the <a href="https://shieldscan.io">ShieldScan</a> team
</p>
