chifleton 0.2.1

Chifleton — lightweight dependency vulnerability scanner using OSV.dev

Chifleton

Dependency vulnerability scanner for U.S. software supply chain security — aligned with Executive Order 14028, NIST SSDF, and CISA guidance.

Project Overview

Chifleton (formerly Chifleton) is a lightweight, open-source supply chain attack vector visibility engine built on OSV. It scans dependency files for known vulnerabilities using OSV.dev and generates evidence-ready reports in the terminal or as HTML/JSON outputs, supporting policy-aligned security workflows.

Python: requirements.txt, pyproject.toml (project.dependencies)
Node.js: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
(Lockfiles are preferred for resolved versions.)

Designed for maintainers and small teams, Chifleton provides transparent dependency security checks without proprietary services or complex setup.

---

Quick Start

pip install .
chifleton scan requirements.txt --report html
# Open scan-report.html

1. Install (from the project directory):

   pip install .
   

2. Create a sample requirements.txt (or use your own):

   requests>=2.28
   Jinja2>=3.1
   

3. Run a scan (generates HTML + JSON by default) and open the report:

   chifleton scan requirements.txt
   # or: python -m scanner scan requirements.txt
   

   Then open scan-report.html in your browser.

4. Open scan-report.html in your browser to view the summary, table of contents, and per-package vulnerability details.

Example commands (copy & paste)

# Scan current dir requirements.txt → terminal + scan-report.html + scan-report.json
chifleton scan
# Same without PATH: python3 -m chifleton scan

# Scan a specific file
chifleton scan path/to/requirements.txt
chifleton scan pyproject.toml
chifleton scan package.json
chifleton scan package-lock.json

# Scan installed packages (exact versions)
pip freeze | chifleton scan - --from-freeze

# Terminal only, no files
chifleton scan --report none

# CI: exit 1 if any vulnerability found
chifleton scan --fail-on-vuln

# Force fresh API calls (no cache)
chifleton scan --no-cache

---

Installation

Requires Python 3.10+.

Install without cloning (use as a binary)

To use the chifleton command globally without cloning the repo:

# From GitHub (no clone)
pip install "git+https://github.com/0x5A65726F677275/Chifleton.git"
# Or
pipx install "git+https://github.com/0x5A65726F677275/Chifleton.git"

Then run from any directory:

chifleton scan requirements.txt --report html
chifleton scan package-lock.json

Install from source (clone 후)

Method	Command	Use case
Install from current directory	pip install .	Normal use; installs the chifleton command.
Editable install (development)	pip install -e ".[dev]"	Work on the code; includes pytest.

Run from the project root. If chifleton is not on your PATH, use python3 -m chifleton scan or python3 -m scanner scan (after installing in a venv, see below).

Linux / WSL (Ubuntu/Debian):

• error: externally-managed-environment — System Python blocks pip install .. Use one of these:

  Option A — Virtual environment (recommended):

  cd /path/to/chifleton
  python3 -m venv .venv
  source .venv/bin/activate
  pip install .
  chifleton scan
  

  Option B — pipx (installs chifleton in an isolated env, no venv needed):

  sudo apt install -y pipx   # if needed
  pipx ensurepath             # add to PATH
  cd /path/to/chifleton
  pipx install .
  chifleton scan
  

• chifleton: command not found — Install in that environment (venv or pipx above), or from an activated venv run: python3 -m chifleton scan (or python3 -m scanner scan).

• pip not found — Install: sudo apt update && sudo apt install -y python3-pip python3-venv

---

CLI Usage

The only subcommand is scan. It takes an optional path to a dependency file (default: requirements.txt in the current directory). Supported inputs: Python — requirements.txt, pyproject.toml ([project.dependencies]), pip-freeze style via --from-freeze; Node.js — package.json, package-lock.json, yarn.lock, pnpm-lock.yaml (lockfile preferred for exact versions).

Basic commands

Action	Command
Scan default requirements.txt	chifleton scan
Scan a specific file	chifleton scan path/to/requirements.txt, chifleton scan pyproject.toml, chifleton scan package.json, chifleton scan package-lock.json
Scan installed packages (pip freeze)	pip freeze | chifleton scan - --from-freeze or chifleton scan frozen.txt --from-freeze
Generate HTML + JSON (default)	chifleton scan (writes both)
Terminal-only (no report files)	chifleton scan --report none
Bypass cache (always query OSV)	chifleton scan --no-cache
CI: fail build if vulns found	chifleton scan --fail-on-vuln

Options

Option	Values	Description
--report	html, json, none	Default: both html and json. html → scan-report.html; json → scan-report.json; none → terminal only.
--no-cache	flag	Disable the local SQLite cache; every run queries the OSV API for each package.
--from-freeze	flag	Input is pip-freeze style (name==version per line). Use path - or omit to read from stdin.
--fail-on-vuln	flag	Exit with code 1 if any vulnerability is found (for CI).

Examples

# Default: terminal + HTML + JSON
chifleton scan

# Terminal-only output
chifleton scan --report none

# Scan actually installed versions (recommended for accurate daily checks)
pip freeze | chifleton scan - --from-freeze
# or save first:
pip freeze > frozen.txt && chifleton scan frozen.txt --from-freeze

# CI: fail the job when vulnerabilities exist
chifleton scan requirements.txt --fail-on-vuln

# Fresh data, no cache (e.g. after OSV updates)
chifleton scan --no-cache --report html

Testing and usage (sample commands)

# Run all tests (from project directory)
pip install -e ".[dev]"
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=scanner --cov-report=term-missing

# Quick smoke test: scan and open report
chifleton scan requirements.txt --report html
# then open scan-report.html in your browser

---

Output

Terminal

Colored summary with per-package results: CVE/OSV IDs, short summary, and remediation hints. A summary table lists all packages with vulnerabilities.

HTML report

Use --report html to generate scan-report.html in the same directory as the scanned file. The report includes:

• Summary — Total packages scanned, packages with vulnerabilities, and total vulnerability count.
• Table of contents — Clickable links to each package section (useful for long reports).
• Per-package sections — Each dependency in its own block with vulnerability count, CVE/OSV IDs, severity (when available), references, and remediation.
• Full-width layout — Readable on large screens; content is not overly constrained.
• Print / PDF-friendly CSS — When printing or saving as PDF: high-contrast text, minimal background color, page breaks between package sections, and link URLs shown after link text.
• Footer attribution — “Report generated by Chifleton — Author: Jaeha Yoo” with generation timestamp (UTC) and version; data-source credit (OSV).

The HTML file is self-contained (no external CSS or JavaScript) and suitable for sharing, archiving, or use as supporting evidence.

JSON report

Use --report json to generate scan-report.json in the same directory as the scanned file. The JSON includes a report object (e.g. generated_at, scanner_version, package_count, total_vulnerabilities) and a packages array with per-package vulnerability details (ids, summary, references, remediation, severity) for use in CI/CD and compliance tooling.

---

Data source

Vulnerability data comes from OSV (Open Source Vulnerabilities), an open, Google-backed database with a standardized API. No proprietary or paid feeds are used.

---

Project structure (for reviewers and new contributors)

High-level layout of the repository:

Path	Purpose
scanner/	Main Python package: CLI, parser, OSV client, cache, reporter, and HTML template.
scanner/templates/	Jinja2 template for the HTML report (bundled so pip install . works).
templates/	Same report template at repo root (for development); keep in sync with scanner/templates/.
tests/	Pytest tests for parser, OSV client, reporter, and CLI.
ARCHITECTURE.md	Design decisions (Python, OSV, SQLite, monolithic CLI).
PROJECT_STRUCTURE.md	Detailed “how it fits together” guide.
ASSESSMENT.md	Project assessment: policy alignment (EO 14028, NIST SSDF, CISA), evidence-ready features, metrics, authorship.
METRICS.md	Test metrics and suggested test cases for reports.
SECURITY.md	How to report security issues (responsible disclosure; GitHub Security Advisories or maintainer).
Dockerfile	Container build for running Chifleton.
pyproject.toml	Package metadata, dependencies, and the chifleton console script.
requirements.txt	Example dependency file; you can run chifleton scan requirements.txt to try the tool.

For a deeper walkthrough, see PROJECT_STRUCTURE.md.

---

National interest and software supply chain security

This project contributes to U.S. software supply chain security and addresses critical supply chain risk in line with U.S. policy and guidance:

• Executive Order 14028 — Improving the Nation’s Cybersecurity: Chifleton supports knowing and documenting dependencies and using transparent, evidence-ready tooling.
• NIST Secure Software Development Framework (SSDF), SP 800-218 — Identifying and managing vulnerabilities in dependencies and producing verifiable, auditable evidence (reports with CVE/OSV IDs, severity, remediation).
• CISA software supply chain security guidance — Dependency and vulnerability visibility and use of open, transparent tooling.

Project contributions:

• Transparent, open-source tooling — No proprietary vulnerability databases or hidden services; a single open data source (OSV) and local-only cache support auditability and use in compliance-sensitive environments.
• Evidence-ready reporting — HTML and JSON reports provide a clear, printable and machine-readable record of dependency checks (summary, per-package results, CVE/OSV IDs, remediation, timestamp, version), suitable for security review and documentation.
• Target users — Maintainers and small teams who may not have access to enterprise vulnerability management, including in government, research, and industry.

For repository-level assessment (policy alignment, evidence-ready features, metrics, attribution), see the root ASSESSMENT.md. For detailed in-repo assessment, see ASSESSMENT.md in this directory.

---

CI and automation

GitHub Actions

Workflows run Chifleton on push and pull requests and publish reports:

• .github/workflows/scan.yml — Installs Chifleton, runs chifleton scan requirements.txt --report html and --report json, writes reports into the repository reports/ folder, and uploads them as workflow artifacts (scan-reports).
• .github/workflows/dependency-scan.yml — Same scan; uploads scan-report.html and scan-report.json from the project directory as separate artifacts.

To use in your repo: copy the workflow and set working-directory to the path containing your requirements.txt, or run chifleton scan path/to/requirements.txt --report html from repo root.

Docker

Build and run Chifleton in a container:

# From the project directory
docker build -t chifleton .

# Scan requirements.txt in the current directory (mount current dir as /work)
docker run --rm -v "$(pwd):/work" -w /work chifleton scan /work/requirements.txt --report html

# Or use default command (scans requirements.txt in /work)
docker run --rm -v "$(pwd):/work" -w /work chifleton

Reports are written into the mounted directory. For JSON: add --report json or run the scan twice (once html, once json).

---

Author / attribution

Author: Jaeha Yoo.
Attribution is consistent across the repository LICENSE, this README, and the HTML/JSON report footers (Chifleton, author name, version, generation timestamp). For full authorship and evidence context, see the root ASSESSMENT.md (Author attribution and contact) or this directory’s ASSESSMENT.md § Authorship / attribution.

---

License

MIT. See the repository LICENSE file.