forj-shieldscan 0.1.0

Scan your code for security issues in 30 seconds

🛡️ ShieldScan

Scan your code for security issues in 30 seconds.

Quick Start • What It Finds • Add to CI • Output Formats • Pro Features

---

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

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

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

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:

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:

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

# 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)

shieldscan scan .

Colored output with severity badges, file locations, fix suggestions, and an overall grade (A+ to F).

JSON

shieldscan scan . --format 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)

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)

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

Fix

Move to environment variable using os.getenv()

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

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

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 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

---

Made with 🛡️ by the ShieldScan team