SecureScope

A 7-stage workflow for context-aware security analysis of open-source dependencies — no loose ends. SecureScope clones a repository, builds a typed graph of its code, configs, secrets, and dependencies, cross-references known CVEs, ranks findings by reachability (not just CVSS), generates remediation, and ships as a CI/CD gate that learns from developer feedback.

Vimalaadhityan (Lead) · Sree Raj Muthaiya · Adhyan Jain — VIT Vellore

The seven stages

#	Stage	What it does	Key tech
01	Ingestion	Clone/profile the repo, build a file inventory	Git, FastAPI, Typer, Pydantic, .securescopeignore
02	Extraction	Parse imports/ASTs, dependency graph, secrets, configs	ast, regex + Shannon entropy, PURL
03	Analysis	CVE lookup + YAML rule engine + taint heuristics	OSV.dev /querybatch, CVSS v3.1 calc, YAML rule pack
04	Correlation	Dedupe, reachability, contextual scoring, suppress	import reachability, suppress.yml
05	Remediation	Version-aware fix hints + diffs per finding	upgrade/patch templates
06	Reporting	SARIF, REST, GraphQL, dashboard	SARIF 2.1.0, FastAPI, Strawberry GraphQL, Next.js
07	CI/CD + Feedback	Merge gate + learning loop	GitHub Action, GitLab, Jenkins, feedback → rule pack

Architecture

Next.js dashboard ──HTTP──▶ FastAPI (REST + GraphQL) ──▶ 7-stage pipeline
                                                  │
        securescope CLI ─────────────────────────┤  (same engine)
                                                  │
        GitHub Action (Docker) ───────────────────┘  → SARIF → Code Scanning

• Backend (backend/app): the pipeline, REST API, GraphQL, SARIF emitter, OSV client, CVSS calculator, YAML rule engine, and the securescope CLI.
• Frontend (app, components, lib): the operator dashboard.

Quick start

# 1. Dependencies
npm install
python3.12 -m pip install --target backend/.vendor -r backend/requirements.txt

# 2. Run the API and the dashboard (two terminals)
npm run api      # http://localhost:8000  (/docs, /graphql)
npm run dev      # http://localhost:3000

# Or the whole stack in Docker:
docker compose up --build

CLI

pip install ./backend                       # installs `securescope`
securescope scan .                          # scan the current repo
securescope scan owner/repo --fail-on high  # scan a GitHub repo
securescope scan . --format sarif -o out.sarif
securescope rulepack                        # show the loaded rule pack
securescope serve                           # run the API

Exit codes: 0 gate passed, 1 gate failed, 2 scan error.

Use as a GitHub Action

- uses: actions/checkout@v4
- uses: Passive-Coder/SecureScope@v1
  id: securescope
  with:
    fail-on: high
    sarif-file: securescope.sarif
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: securescope.sarif

This repository dogfoods its own action in .github/workflows/securescope.yml.

Configuration

securescope.yml (gate + scan options) and .securescope/suppress.yml (suppressions) at the repo root, plus .securescopeignore for inventory exclusions. See the files in this repo for working examples.

OSV.dev

Stage 03 queries the live OSV.dev database for real CVEs and derives severity from each advisory's CVSS vector using the bundled v3.1 calculator. Set SECURESCOPE_OFFLINE=1 (or --offline) to use only the bundled rule pack — CI runs offline for determinism.

Verify

npm run lint                       # tsc --noEmit
npm run build                      # next build
PYTHONPATH=backend npm run test:api # pytest (or: pytest backend/tests)

Deployment

Docker, single-binary CLI, Helm chart, and Vercel + Railway — see deploy/README.md.