CLI & engine overview

vulnmgmt is the original Python engine and command-line tool behind Lockstep VM. It predates the webapp and is a self-contained vulnerability-management pipeline: it ingests a software inventory, maps applications to CVEs, enriches those CVEs with threat intelligence, scores and prioritizes them, and generates reports or persists findings to a database.

It is a Click-based CLI built with Rich for terminal output, and it is PostgreSQL-backed.

How it relates to the webapp

The engine and the webapp are two distinct applications that share one library.

	`vulnmgmt` engine (this)	Webapp
Interface	Click CLI (`vulnmgmt …`)	FastAPI REST API + React frontend
Datastore	PostgreSQL (SQLAlchemy)	MongoDB (Motor async driver)
Primary use	Batch scans, enrichment, report generation, background sync jobs	Interactive multi-source inventory & reconciliation
Config	`.env` / `.env.local`, `pydantic-settings`	env-driven `pydantic-settings`

The two are not competitors — the webapp imports directly from the engine. The FastAPI backend reuses the engine’s integration clients and pipeline components rather than re-implementing them, for example:

# webapp/backend/app/api/v1/endpoints/…
from vulnmgmt.integrations.sentinelone.client import SentinelOneClient
from vulnmgmt.integrations.rapid7.client import Rapid7Client
from vulnmgmt.integrations.epss.client import EPSSClient
from vulnmgmt.integrations.greynoise.client import GreyNoiseClient
from vulnmgmt.integrations.virustotal.client import VirusTotalClient
from vulnmgmt.research.cve_lookup import CVEResearcher
from vulnmgmt.mapping import CVEMapper
from vulnmgmt.intelligence import ThreatIntelligenceAggregator
from vulnmgmt.inventory import Application

So vulnmgmt.integrations (plus research, mapping, intelligence, inventory) is effectively a shared library consumed by both the CLI and the webapp. The no-credential CVE data sources — nvd, epss, cpe, cve_awg, cvelist — are the most reused because they need no key-manager state.

Subpackage map

The package lives at src/vulnmgmt/. The CLI entry point is cli.py, with additional command groups in the cli_*.py modules (see CLI commands).

Subpackage	Responsibility
`analysis`	Legacy risk scoring (`RiskAnalyzer`, `DeepAnalyzer`) and software version tracking (`version_tracker`)
`config`	`pydantic-settings` `Settings` (`get_settings()`) — API keys, rate limits, output/data dirs
`core`	Pandas-based inventory processor (`VulnerabilityProcessor`), pydantic models (`Application`, `Vendor`, `Vulnerability`, `RiskScore`, enums), and vendor normalization tables
`database`	PostgreSQL schema (`schema.sql`), reporting views (`views.sql`), SQLAlchemy models, and engine/session setup
`integrations`	The shared client library — ~19 external platform & threat-intel API clients plus the encrypted `key_manager`
`intelligence`	`ThreatIntelligenceAggregator` — enriches CVEs across many sources into `EnrichedCVE` records
`inventory`	`ApplicationInventory` / `Application` — normalizes raw software rows from CSV/Intune/Rapid7/Defender
`mapping`	`CVEMapper` — maps applications to CVEs via CPE resolution and NVD version-range matching
`output`	Report generators — Excel (`ExcelReportGenerator`), DOCX, PDF, and per-platform report builders
`remediation`	Remediation workflow state machine (`RemediationWorkflow`) and SLA/MTTR metrics (`SLATracker`)
`research`	`CVEResearcher` — multi-source CVE lookup (NVD, CVE.org, CISA KEV) and research-URL helpers
`scoring`	`RiskScoringEngine` — six-factor weighted 0–100 risk score with `Priority`
`worker`	APScheduler background jobs — Rapid7 sync, enrichment, SLA checks, software import/matching, daily reports

For how these fit together end-to-end, see the Processing pipeline.

Install & run

The package is defined in pyproject.toml (name = "vuln-management", Python ≥ 3.10, hatchling build). It exposes two console entry points that both resolve to vulnmgmt.cli:main:

[project.scripts]
vulnmgmt = "vulnmgmt.cli:main"
vm       = "vulnmgmt.cli:main"

Install it (editable, for development) and run:

# from the repo root
pip install -e .           # or: uv pip install -e .

# confirm the CLI resolves
vulnmgmt --help
vulnmgmt info              # show configuration & feature list

Running vulnmgmt with no subcommand prints a Rich welcome panel listing the available command groups. Configuration is read from a .env file (vulnmgmt.config.settings.Settings) — notably NVD_API_KEY for higher NVD rate limits — and threat-intel API keys are read from .env.local (see the CLI commands page). The PostgreSQL connection is configured via DATABASE_URL.

Typical first commands

# Look up CVEs for one app and enrich + score them
vulnmgmt vuln lookup --app "Foxit Reader" --version "7.1.5" --enrich

# Search the NVD CPE dictionary
vulnmgmt cpe search "Foxit Reader"

# Run the full Intune inventory scan
vulnmgmt intune scan AppInvRawData.csv --top 20

# Initialize the database schema
vulnmgmt db init