Metadata-Version: 2.4
Name: prism-sast-scanner
Version: 0.1.1
Summary: PRISM — Multi-engine security scanner for GitHub Actions and CI/CD pipelines
License-Expression: MIT
Project-URL: Homepage, https://github.com/bhargav1815/prism-action
Project-URL: Repository, https://github.com/bhargav1815/prism-action
Project-URL: Bug Tracker, https://github.com/bhargav1815/prism-action/issues
Project-URL: Changelog, https://github.com/bhargav1815/prism-action/releases
Keywords: security,scanner,sast,sca,secrets,github-actions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: pip-audit>=2.7.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: openai>=1.35.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: click>=8.1.0
Dynamic: license-file

# PRISM Security Scanner

[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-PRISM%20Security%20Scanner-blue?logo=github)](https://github.com/marketplace/actions/prism-security-scanner)
[![PyPI](https://img.shields.io/pypi/v/prism-scanner?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/prism-scanner/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)](https://pypi.org/project/prism-scanner/)

**PRISM** is a privacy-first, multi-engine security scanner built for GitHub Actions and CI/CD pipelines. It detects secrets, vulnerable dependencies, insecure code patterns, and taint-flow vulnerabilities — all without sending your source code to any third-party server.

---

## Why PRISM?

| Feature | Snyk | Trivy | SonarQube | PRISM |
|---|:---:|:---:|:---:|:---:|
| Secrets detection | ✓ | ✓ | — | ✓ |
| SCA (dependency audit) | ✓ | ✓ | ✓ | ✓ |
| AST / SAST rules | — | — | ✓ | ✓ |
| Taint-flow tracking | — | — | ✓ | ✓ |
| AI fix suggestions (BYOK) | — | — | — | ✓ |
| Single `.docx` + HTML report | — | — | — | ✓ |
| Source code stays on runner | — | — | — | ✓ |
| Free, self-hosted | — | ✓ | — | ✓ |

---

## Engines

| Engine | What it finds |
|---|---|
| **Secrets Scanner** | Hardcoded API keys, tokens, passwords — 20+ patterns with Shannon entropy validation |
| **SCA Scanner** | Known CVEs in Python (`pip-audit`), JavaScript (`npm audit`), Ruby (`bundler-audit`), Go (`govulncheck`) |
| **AST Scanner** | OWASP Top 10 patterns for Python, JavaScript, and Java via tree-sitter — 44 rules |
| **Taint Tracker** | Source-to-sink taint flows: Flask/Express/Spring inputs reaching SQL, OS commands, eval, or XSS sinks |

---

## How it works — PR Gate

This is the primary use-case: **PRISM blocks a merge to `main` if security findings are found.**

```
Developer opens PR
       │
       ▼
GitHub spins up a fresh Ubuntu VM (runner)
       │
       ▼
actions/checkout — clones the PR branch onto the VM
       │
       ▼
PRISM is pulled from PyPI and installed (pip install prism-scanner)
       │
       ▼
PRISM scans the code on the VM — nothing leaves the VM
       │
       ├─ Findings found above threshold?
       │         │
       │         ▼
       │   Posts summary comment on the PR  ◄── developers see it instantly
       │   Uploads HTML/DOCX report as artifact
       │   Fails the job → merge is BLOCKED
       │
       └─ Clean scan?
                 │
                 ▼
           Posts ✅ comment on PR
           Merge is ALLOWED
```

The VM is destroyed after the run. Your source code never leaves it.

---

## Quick Start — GitHub Actions

Add this file to your repository at `.github/workflows/prism.yml`:

```yaml
name: PRISM Security Scan

on:
  pull_request:              # runs on every PR — blocks merge if findings found
  push:
    branches: [main]         # also runs after merge as a safety net

jobs:
  prism:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write   # needed so PRISM can post a comment on the PR

    steps:
      - uses: actions/checkout@v4

      - uses: prism-security/prism-action@v1
        with:
          fail-on-severity: HIGH        # CRITICAL | HIGH | MEDIUM | LOW
          report-format: both           # docx | html | both
          github-token: ${{ secrets.GITHUB_TOKEN }}   # enables PR comments
```

`secrets.GITHUB_TOKEN` is **automatically provided by GitHub** — you do not need to create it. PRISM uses it only to post a comment on the PR.

PRISM will:
1. Scan the PR branch on the runner VM
2. Post a findings summary table as a comment on the PR
3. Upload the full HTML + DOCX report as a downloadable artifact
4. **Block the merge** if findings at or above `fail-on-severity` are found

---

## Quick Start — CLI (local / any CI)

```bash
pip install prism-scanner

# Scan any project directory
prism scan --target ./my-project --report-format both --fail-on-severity HIGH
```

The report is saved to `prism-output/<project>_prism_security_report_<timestamp>.html` (and `.docx`).

---

## AI-Powered Tier (Premium — BYOK)

PRISM optionally integrates with **your own** Azure OpenAI deployment to:
- Filter false positives automatically
- Provide AI-generated fix descriptions
- Generate a complete corrected code block ready to paste
- Re-score risk based on context

**Your source code is never sent to AI** — only the finding metadata (file, line, rule, 500-char snippet) is sent, and only to the endpoint you own.

### GitHub Actions

```yaml
      - uses: prism-security/prism-action@v1
        with:
          fail-on-severity: HIGH
          report-format: both
          azure-openai-key: ${{ secrets.PRISM_AZURE_OPENAI_KEY }}
          azure-openai-endpoint: ${{ secrets.PRISM_AZURE_OPENAI_ENDPOINT }}
          azure-openai-deployment: gpt-4o   # your deployment name
```

Store your Azure credentials in **Settings → Secrets and variables → Actions** in your repository. They are passed only as environment variables to the runner — never logged or transmitted elsewhere.

### CLI (local)

```powershell
# Windows PowerShell
$env:PRISM_AZURE_OPENAI_KEY      = "your-key"
$env:PRISM_AZURE_OPENAI_ENDPOINT = "https://your-resource.openai.azure.com/"
$env:PRISM_AZURE_OPENAI_DEPLOYMENT = "gpt-4o"

prism scan --target ./my-project --report-format both
```

```bash
# Linux / macOS
export PRISM_AZURE_OPENAI_KEY="your-key"
export PRISM_AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export PRISM_AZURE_OPENAI_DEPLOYMENT="gpt-4o"

prism scan --target ./my-project --report-format both
```

---

## All Inputs

| Input | Default | Description |
|---|---|---|
| `target` | `.` | Path to the directory to scan (relative to repo root) |
| `fail-on-severity` | `HIGH` | Fail if findings at or above this level: `LOW` `MEDIUM` `HIGH` `CRITICAL` |
| `report-format` | `both` | Report output format: `docx` `html` `both` |
| `github-token` | _(empty)_ | Pass `secrets.GITHUB_TOKEN` to enable PR comment summaries |
| `azure-openai-key` | _(empty)_ | Azure OpenAI key — enables Premium AI features |
| `azure-openai-endpoint` | _(empty)_ | Azure OpenAI endpoint URL |
| `azure-openai-deployment` | `gpt-4o` | Azure OpenAI deployment name |
| `custom-rules` | _(empty)_ | Path to a custom YAML rules file |
| `enable-container-scan` | `false` | Enable Trivy container/IaC scanning (requires Trivy on runner) |
| `dry-run-ai` | `false` | Print AI prompt to console without sending — for auditing |

## Outputs

| Output | Description |
|---|---|
| `findings-count` | Total number of findings |
| `critical-count` | Number of CRITICAL findings |
| `high-count` | Number of HIGH findings |
| `report-path` | Path to the generated report file(s) |

---

## CI/CD Integration Examples

### GitLab CI

```yaml
prism-scan:
  image: python:3.12-slim
  stage: test
  script:
    - pip install prism-scanner
    - prism scan --target . --report-format html --fail-on-severity HIGH
  artifacts:
    when: always
    paths:
      - prism-output/
```

### Azure DevOps

```yaml
- task: UsePythonVersion@0
  inputs:
    versionSpec: "3.12"

- script: pip install prism-scanner
  displayName: Install PRISM

- script: prism scan --target . --report-format both --fail-on-severity HIGH
  displayName: Run PRISM Security Scan
  env:
    PRISM_AZURE_OPENAI_KEY: $(PRISM_AZURE_OPENAI_KEY)
    PRISM_AZURE_OPENAI_ENDPOINT: $(PRISM_AZURE_OPENAI_ENDPOINT)

- task: PublishBuildArtifacts@1
  condition: always()
  inputs:
    PathtoPublish: prism-output
    ArtifactName: prism-security-report
```

### Jenkins

```groovy
stage('PRISM Security Scan') {
    steps {
        sh 'pip install prism-scanner'
        sh 'prism scan --target . --report-format html --fail-on-severity HIGH'
    }
    post {
        always {
            archiveArtifacts artifacts: 'prism-output/**', allowEmptyArchive: true
        }
    }
}
```

### Bitbucket Pipelines

```yaml
- step:
    name: PRISM Security Scan
    image: python:3.12-slim
    script:
      - pip install prism-scanner
      - prism scan --target . --report-format html --fail-on-severity HIGH
    artifacts:
      - prism-output/**
```

---

## Custom Rules

Write your own detection rules in YAML and pass them via `--custom-rules`:

```yaml
# my-rules.yml
rules:
  - id: no-eval
    severity: HIGH
    message: "Avoid eval() — execute arbitrary code vulnerability"
    pattern: "eval\\s*\\("
    cwe: CWE-95
    owasp: A03:2021
    languages: [python, javascript]
```

```bash
prism scan --target ./my-project --custom-rules ./my-rules.yml
```

---

## Privacy & Security

- **Source code never leaves your runner.** All engines execute locally.
- **AI tier (optional):** Only finding metadata is sent — file path, line number, rule ID, and a 500-character code snippet. No full files, no tokens, no credentials.
- **BYOK:** You use your own Azure OpenAI subscription. PRISM has no backend.
- **Audit mode:** Run with `--dry-run-ai true` to print exactly what would be sent to AI before enabling it.

---

## Supported Languages

| Language | Secrets | SCA | AST / OWASP | Taint |
|---|:---:|:---:|:---:|:---:|
| Python | ✓ | ✓ | ✓ | ✓ |
| JavaScript / TypeScript | ✓ | ✓ | ✓ | ✓ |
| Java | ✓ | — | ✓ | ✓ |
| Ruby | ✓ | ✓ | — | — |
| Go | ✓ | ✓ | — | — |

---

## License

MIT — free to use, modify, and distribute. See [LICENSE](LICENSE).

---

*Generated by PRISM Security Scanner — all scan data processed locally on your runner.*
