vulnlens 0.3.0__tar.gz

vulnlens-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harish Akshay H
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vulnlens-0.3.0/PKG-INFO

@@ -0,0 +1,368 @@
+Metadata-Version: 2.4
+Name: vulnlens
+Version: 0.3.0
+Summary: Security scanner that sorts code, dependency and secret findings into Act now / Review / Context, using CISA KEV, EPSS and CVSS.
+Author: Harish Akshay H
+License-Expression: MIT
+Project-URL: Homepage, https://harishakshay.github.io/open-source-vulnerability-scanner/
+Project-URL: Source, https://github.com/harishakshay/open-source-vulnerability-scanner
+Project-URL: Issues, https://github.com/harishakshay/open-source-vulnerability-scanner/issues
+Project-URL: Changelog, https://github.com/harishakshay/open-source-vulnerability-scanner/blob/main/CHANGELOG.md
+Keywords: security,sast,sca,cve,epss,kev,sarif,secrets,vulnerability-scanner,devsecops
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ai
+Requires-Dist: anthropic>=1.0; extra == "ai"
+Provides-Extra: semgrep
+Requires-Dist: semgrep>=1.100; extra == "semgrep"
+Provides-Extra: all
+Requires-Dist: anthropic>=1.0; extra == "all"
+Requires-Dist: semgrep>=1.100; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# VulnLens
+
+[![CI](https://github.com/harishakshay/open-source-vulnerability-scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/harishakshay/open-source-vulnerability-scanner/actions/workflows/ci.yml)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![Dependencies: stdlib only](https://img.shields.io/badge/runtime%20deps-stdlib%20only-success)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**A security scanner that tells you which findings actually matter.**
+
+**[Live demo →](https://harishakshay.github.io/open-source-vulnerability-scanner/)** · an interactive
+report of a real scan; no install needed.
+
+Security scanners report hundreds of issues, so developers stop reading them. VulnLens runs
+three engines (code, dependencies and secrets) and then ranks every finding by **real-world
+exploitation evidence** instead of severity alone:
+
+- **CISA KEV**: is this CVE being exploited in the wild *right now*?
+- **EPSS** (FIRST.org): how likely is exploitation in the next 30 days?
+- **CVSS v3**: how bad is it if exploited? (computed from the vector, not guessed)
+- **TruffleHog verification**: is the leaked credential actually live?
+
+Every finding lands in one of three piles, by the strength of the evidence:
+
+| | What's in it |
+|---|---|
+| **Act now** | An exploited or likely-exploited CVE (KEV, high EPSS) in a runtime dependency, a verified live secret, or a flaw AI triage confirmed |
+| **Review** | A signal in shipped code that needs a judgment: a risky code pattern, an unverified key, a CVE nobody is known to exploit |
+| **Context** | The same signals in tests, examples, docs, vendored code or dev dependencies |
+
+You also get an upgrade plan that collapses dozens of CVEs into a few version bumps, a dashboard,
+and SARIF for the GitHub Security tab.
+
+## Quickstart (about 5 minutes)
+
+```bash
+pip install "vulnlens[semgrep] @ git+https://github.com/harishakshay/open-source-vulnerability-scanner"
+vulnlens doctor                    # checks the engines, prints the install step for anything missing
+vulnlens scan .                    # Act now / Review / Context in the terminal
+vulnlens scan . --html report.html # the full interactive report, one offline file
+```
+
+Then add it to CI so new Act-now findings fail the build: see [GitHub Action](#github-action).
+Python 3.10+, no runtime dependencies beyond the standard library. TruffleHog (the secrets engine)
+is a separate binary; `vulnlens doctor` names the exact release file for your OS.
+
+![VulnLens dashboard: priority breakdown, exploitability map and fix-first list for OWASP PyGoat](https://raw.githubusercontent.com/harishakshay/open-source-vulnerability-scanner/main/docs/images/overview-dark.png)
+
+<sub>[OWASP PyGoat](https://github.com/adeyosemanputra/pygoat), an intentionally vulnerable app: 273 findings,
+11 to act on now, and the one CVE that is being actively exploited ranked first. The **exploitability map** plots
+every dependency CVE by severity (CVSS) against likelihood of exploitation (EPSS); the dashed lines
+are the P1 thresholds. [Light mode](https://raw.githubusercontent.com/harishakshay/open-source-vulnerability-scanner/main/docs/images/overview.png) ·
+[findings](https://raw.githubusercontent.com/harishakshay/open-source-vulnerability-scanner/main/docs/images/findings.png) · [upgrade plan](https://raw.githubusercontent.com/harishakshay/open-source-vulnerability-scanner/main/docs/images/upgrade-plan.png)</sub>
+
+```
+$ vulnlens scan https://github.com/adeyosemanputra/pygoat
+scanned 2026-10-16T16:31:30+00:00 in 100.0s
+
+  semgrep     ok               86 finding(s)
+  osv         ok              187 finding(s)  46 packages from 4 file(s)
+  trufflehog  ok                0 finding(s)  verification disabled
+
+  Grade:  F    273 findings
+  Act now: 11   Review: 242   Context: 20
+  P0: 1   P1: 23   P2: 84   P3: 147   P4: 18
+  1 actively exploited (CISA KEV)
+
+  Upgrade plan: 21 upgrade(s) resolve 186 dependency finding(s)
+    P0 Pillow 9.4.0 -> 12.3.0  (19 vuln(s))  KEV  requirements.txt
+    P1 Django 4.2 -> 5.2.17  (51 vuln(s))  requirements.txt
+    P1 django 3.2.18 -> 5.2.17  (20 vuln(s))  dockerized_labs/sensitive_data_exposure/requirements.txt
+    P1 PyJWT 2.4.0 -> 2.15.0  (13 vuln(s), 1 unfixed)  requirements.txt
+
+  Act now (11): evidence of real risk in shipped code
+   1. P0 Pillow 9.4.0: libwebp: OOB write in BuildHuffmanTable
+      requirements.txt:19  [osv: GHSA-j7hp-h8jx-5ppr]
+      - In CISA KEV: actively exploited in the wild (listed 2023-09-13)
+      - EPSS: 99.98% chance of exploitation in the next 30 days (riskier than 99.98% of CVEs)
+      - CVSS 8.8 (high)
+      - Fix: upgrade Pillow to 10.0.1 or later
+   2. P1 django 3.2.18: Django potential denial of service vulnerability in UsernameField on Win...
+      dockerized_labs/sensitive_data_exposure/requirements.txt:1  [osv: GHSA-qmf9-6jqf-j8fq]
+      - EPSS: 49.8% chance of exploitation in the next 30 days (riskier than 98.9% of CVEs)
+      - CVSS 7.5 (high)
+      - Fix: upgrade django to 3.2.23 or later
+   ...
+  ...and 249 more to act on or review. Use --top, --html or --format json for the full list.
+  20 more in tests, examples, docs or dev dependencies (Context).
+
+  Next
+    vulnlens scan https://github.com/adeyosemanputra/pygoat --html report.html   full interactive report (one offline file)
+    add --ai-dry-run, then --ai-triage    let Claude judge the Review pile (shows the cost first)
+    add it to CI: see 'GitHub Action' in the README (fails the build on Act-now findings)
+```
+
+*(Real output from scanning [OWASP PyGoat](https://github.com/adeyosemanputra/pygoat), an
+intentionally vulnerable app, on 2026-10-16: 273 findings, 11 to act on now, and the one CVE in
+active exploitation ranked first.)*
+
+## How prioritization works
+
+| Priority | Meaning | Rule |
+|---|---|---|
+| **P0** | Fix now | CVE is in CISA KEV, or a secret is **verified live** |
+| **P1** | Fix this sprint | EPSS ≥ 10%, CVSS ≥ 9.0, or a high-severity code flaw that is high-confidence or also flagged by a rule from another rule family |
+| **P2** | Plan a fix | High severity, or EPSS ≥ 1% |
+| **P3** | Low | Medium severity, or an unverified secret |
+| **P4** | Informational | Everything else |
+
+Findings in code that doesn't ship (tests, examples, docs, vendored copies) and development-only
+dependencies are **capped at P3**, with the reason shown. A verified live secret stays P0 wherever it is.
+
+Each finding includes the **reasons** for its priority, so the ranking can be checked rather
+than taken on trust. The rules live in [`vulnlens/priority.py`](https://github.com/harishakshay/open-source-vulnerability-scanner/blob/main/vulnlens/priority.py).
+
+### Noise reduction
+
+- **Alias merging**: the same vulnerability often appears as `GHSA-…`, `PYSEC-…` and `CVE-…`.
+  VulnLens merges them with union-find over OSV aliases and keeps the record with the best data.
+- **Same-line merging**: several Semgrep rules often flag one bug (three rules fired on one SQL
+  injection line in the demo app). They are reported once; agreement counts as corroboration only
+  between different rule families, since sibling rules usually encode the same pattern.
+- **One finding per vulnerable package**: a package pinned in many lockfiles (monorepos, example
+  folders) is reported once, pointing at the production file, with the other files listed.
+- **Implausible secrets are dropped**: an unverified match that is a code identifier, a placeholder
+  (`YOUR_API_KEY`), a local dev URL or low-randomness text is not reported (verified ones always are).
+- **Upgrade plan**: for each vulnerable package, the smallest version that fixes everything found.
+  It picks the *nearest* fix on your version line (Django 3.2.0 → 3.2.14, not 4.0.6).
+- **Secrets are never echoed**: only TruffleHog's redacted form ever reaches the output.
+
+## AI triage (optional)
+
+```bash
+pip install "vulnlens[ai] @ git+https://github.com/harishakshay/open-source-vulnerability-scanner"
+export ANTHROPIC_API_KEY=...
+vulnlens scan . --ai-triage
+```
+
+Static analysers match patterns. With `--ai-triage`, Claude (`claude-haiku-5-5`, the cheapest model, by default; `--ai-model` picks another) reads
+each code finding together with about 60 lines of surrounding source and returns a structured
+verdict: **real**, **false positive** or **needs review**, with a confidence, the reasoning, an
+exploit scenario and a suggested fix.
+
+- A confident *false positive* drops to P3 "Low", never lower: the AI alone cannot make a finding
+  disappear, and a finding whose code contains text aimed at AI reviewers keeps its priority.
+- A high-confidence *real* finding moves up one priority level (never above P1).
+- Only code findings are sent, and each snippet is **redacted first**: lines where a secret was
+  found are blanked and key-shaped strings (API keys, tokens, private keys, URL passwords) are
+  masked. Secret findings themselves are never sent; dependency findings are ranked by KEV/EPSS.
+- Verdicts are cached per code snippet, so re-scanning unchanged code costs nothing. Before any
+  call, VulnLens prints an estimated cost; `--ai-dry-run` shows it and sends nothing, and triage is
+  skipped if the estimate is above `--ai-max-cost` (default $2). `--ai-max` caps how many findings
+  are reviewed, most urgent first. Every scan reports what triage actually cost.
+
+How accurate is it? On [`evals/triage`](https://github.com/harishakshay/open-source-vulnerability-scanner/tree/main/evals/triage), 54 labeled findings from OWASP PyGoat and Flask, Claude Haiku 5.5 dismissed 17 findings as false positives and **all 17 were** (61% of the false positives removed), wrongly dismissed **0 of 26** real issues, and cost **$0.035** for the run. One label was corrected after the run (the model turned out to be right); with the original labels precision was 94% and one real issue was missed. Labels were checked by Claude Opus 5.5, not a human security expert, and the sample is small, so treat these as a first measurement.
+
+## Install
+
+```bash
+pip install "vulnlens[semgrep] @ git+https://github.com/harishakshay/open-source-vulnerability-scanner"
+vulnlens doctor              # checks every engine and prints the exact install step for anything missing
+```
+
+TruffleHog (the secrets engine) is a separate binary: `vulnlens doctor` names the release file for
+your OS. VulnLens recommends TruffleHog 3.99.2 and warns on anything older than 3.88, whose
+detectors are much noisier.
+
+The dependency engine needs no binary: it parses lockfiles itself and queries the
+[OSV.dev](https://osv.dev) API. Missing engines are reported as `NOT INSTALLED`, and the scan
+is marked incomplete. An incomplete scan gets grade `?` instead of a letter, so a partial scan
+never looks clean.
+
+**Supported lockfiles:** `requirements*.txt`, `Pipfile.lock`, `poetry.lock`, `uv.lock`,
+`pyproject.toml` (exact `==` pins; ignored next to a lockfile), `package-lock.json`,
+`npm-shrinkwrap.json`, `yarn.lock` (classic + berry), `pnpm-lock.yaml`, `go.mod` (with `replace`),
+`Cargo.lock`, `composer.lock`, `Gemfile.lock`. Dependency files VulnLens can't read yet
+(`pom.xml`, `build.gradle`, `bun.lock`, ...) and dependencies without an exact version are listed
+under **Not checked** in every report, so a good grade is never mistaken for full coverage.
+
+## Usage
+
+```bash
+vulnlens scan .                                        # terminal report
+vulnlens scan https://github.com/owner/repo            # shallow, hook-free clone of a public repo
+vulnlens scan . --sarif results.sarif --json report.json
+vulnlens scan . --fail-on P1                           # exit 1 if anything is P0/P1 (CI gate)
+vulnlens scan . --engines deps                         # only dependencies
+vulnlens scan . --offline --semgrep-config rules.yml   # no network (registry rulesets need semgrep.dev)
+vulnlens scan . --exclude 'tests/**'                   # skip paths (repeatable)
+vulnlens scan . --baseline main.json --fail-on P1      # only fail on findings new since main.json
+```
+
+Remote repository URLs are never secret-verified: those credentials aren't yours to test.
+
+### Silencing findings
+
+A `.vulnlensignore` file at the scan root takes path globs and `rule:`, `id:` (advisory or CVE)
+and `fingerprint:` entries, each with an optional `# reason`. A `vulnlens: ignore` comment on the
+flagged line or the line above silences it there (`vulnlens: ignore[rule-glob]` limits it to
+matching rules). Every suppression is listed with its reason in the JSON report. A remote
+repository's own ignore rules are not honored, so its author can't hide findings from you.
+Fingerprints come from the flagged line's content, not its number, so they stay stable as code moves.
+
+Exit codes: `0` ok, `1` findings at or above `--fail-on`, `2` scan error (bad target, or with
+`--fail-on`, any engine that did not run, so a CI gate never passes on a partial scan).
+
+## Web dashboard and HTML reports
+
+```bash
+vulnlens serve                                  # http://localhost:8765 (keeps the last 50 scans)
+vulnlens serve --load report.json               # browse a saved `scan --json` report
+vulnlens scan . --html report.html              # standalone report: one file, opens offline
+vulnlens html a.json b.json -o site/index.html  # bundle several saved reports into one page
+```
+
+The standalone HTML report is the same dashboard with the results embedded. Attach it to a ticket,
+publish it as a CI artifact, or host it as a static page.
+
+Start scans from the browser, watch progress live, filter findings by priority, type or text,
+expand any finding to see *why* it got its priority, and download JSON or SARIF. It uses the
+standard library only, with no build step or CDN, so it works offline.
+
+The server binds to `127.0.0.1` and rejects requests whose `Host` or `Origin` is not itself, so a
+malicious website cannot use your browser to start scans (DNS rebinding / CSRF). All scan data is
+rendered as text, never as HTML, because findings contain content from the scanned repository.
+
+## GitHub Action
+
+```yaml
+# .github/workflows/vulnlens.yml
+name: VulnLens
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+  security-events: write   # upload results to Security → Code scanning
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: harishakshay/open-source-vulnerability-scanner@v0
+        id: vulnlens
+        with:
+          fail-on: act        # fail only on Act-now findings; use `review` to be stricter
+      - if: always()
+        run: echo "Act now ${{ steps.vulnlens.outputs.act }}, review ${{ steps.vulnlens.outputs.review }}"
+```
+
+The Action installs VulnLens, Semgrep and TruffleHog (downloaded from its release and checked
+against the published SHA-256), scans, writes a job summary, and uploads SARIF. Act-now findings
+appear as errors in **Security → Code scanning**, Review as warnings, Context as notes.
+
+| Input | Default | |
+|---|---|---|
+| `path` | `.` | directory to scan |
+| `fail-on` | *(never)* | `act`, `review`, or a priority `P0`-`P4` |
+| `engines` | `code,deps,secrets` | |
+| `baseline` | | an earlier JSON report: only new findings count (useful on pull requests) |
+| `upload-sarif` | `true` | needs `security-events: write` |
+| `semgrep-config` | `p/default` | |
+
+Outputs: `act`, `review`, `context`, `grade`, `sarif-file`. Pin `@v0` for every 0.x release or
+`@v0.3.0` for an exact one.
+
+## Architecture
+
+```
+vulnlens/
+  cli.py            argument parsing, outputs, exit codes
+  scan.py           runs engines in parallel, enriches, prioritizes
+  source.py         local path or safe remote clone (https + host allow-list + public-IP check)
+  engines/
+    semgrep.py      SAST, plus same-line / same-weakness merging
+    deps.py         lockfiles -> OSV.dev
+    secrets.py      TruffleHog with verification, redacted output
+  lockfiles.py      13 lockfile/manifest parsers, dev-dependency flags, unpinned counts
+  context.py        prod / test / example / docs / vendored classification
+  ignore.py         .vulnlensignore, inline ignores, --exclude, --baseline
+  doctor.py         `vulnlens doctor`: engine and network checks with install steps
+  intel/
+    osv.py          batch query, alias de-duplication, fixed versions
+    cvss.py         CVSS v3.0/v3.1 base-score calculator (FIRST spec)
+    exploit.py      EPSS + CISA KEV with on-disk cache
+  priority.py       P0-P4 rules and A-F grade
+  triage.py         AI triage with Claude: structured verdicts, caching, cost tracking
+  fixplan.py        per-package upgrade plan
+  sarif.py          SARIF 2.1.0 for GitHub code scanning
+  server.py         `vulnlens serve`: local dashboard API (stdlib http.server)
+  web/index.html    dashboard UI: prebuilt single file from web/dashboard (React + TypeScript + Tailwind)
+  htmlreport.py     standalone HTML export (dashboard with results embedded)
+```
+
+No runtime dependencies beyond the Python standard library.
+
+## Limitations
+
+- Dependency findings mean a vulnerable version is *installed*, not that the vulnerable function is
+  *reachable* from your code. Reachability analysis is on the roadmap.
+- Dependencies without an exact version (`requests>=2.0`) can't be matched to advisories. They
+  are counted and listed under "Not checked"; a lockfile gives the most accurate results.
+- Semgrep registry rulesets (`p/default`) change over time, so the same commit can give slightly
+  different code findings later. Each report records the Semgrep version and ruleset used.
+- On Python 3.10 (no `tomllib`), `pyproject.toml` is read for exact `"name==x"` pins only: Poetry
+  tables, dev groups and unpinned counts need Python 3.11+.
+- CVSS v4-only advisories fall back to the advisory's severity label.
+- Version ordering for the upgrade plan is ecosystem-agnostic, so check unusual version schemes.
+
+## Roadmap
+
+- [x] **AI triage** with Claude, plus a labeled evaluation set (`evals/triage`)
+- [ ] Reachability: is the vulnerable function actually called?
+- [x] Local web dashboard (`vulnlens serve`)
+- [ ] PR comments
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+python -m vulnlens scan examples/demo-app     # deliberately vulnerable sample
+```
+
+See [CONTRIBUTING.md](https://github.com/harishakshay/open-source-vulnerability-scanner/blob/main/CONTRIBUTING.md) to get involved, [SECURITY.md](https://github.com/harishakshay/open-source-vulnerability-scanner/blob/main/SECURITY.md) to report a
+vulnerability, and [CHANGELOG.md](https://github.com/harishakshay/open-source-vulnerability-scanner/blob/main/CHANGELOG.md) for release notes.
+
+MIT License.