Integrations library

vulnmgmt.integrations is the shared client library used by the legacy vulnmgmt CLI/engine. Every external system — EDR/RMM asset sources, vuln scanners, the ConnectWise PSA, and roughly a dozen threat-intelligence feeds — is reached through a client class in this package. Almost every client subclasses a single base, so they share retry logic, session handling, and a common shape.

Everything imports from one place:

from vulnmgmt.integrations import (
    # Vulnerability / asset management
    Rapid7Client, DefenderClient, SentinelOneClient,
    # Threat intelligence
    XForceClient, VirusTotalClient, OTXClient, AbuseIPDBClient, MITREClient,
    PhishTankClient, URLhausClient, GreyNoiseClient, ShodanClient,
    CVEListClient, SpamhausClient,
)

A handful of clients live in their own subpackages and are imported directly rather than re-exported at top level: nvd.NVDClient, epss.EPSSClient, cve_awg.CVEAWGClient, cpe.CPEClient, and connectwise.ConnectWiseClient.

The contract: `BaseIntegration` + `IntegrationConfig`

integrations/base.py defines the common contract. IntegrationConfig is a dataclass that carries connection settings; BaseIntegration is an abstract base that owns a pre-configured requests.Session.

@dataclass
class IntegrationConfig:
    api_key: str
    api_url: str
    region: Optional[str] = None
    timeout: int = 30
    max_retries: int = 3
    verify_ssl: bool = True
    rate_limit_delay: float = 0.5
    organization_id: Optional[str] = None
    tenant_id: Optional[str] = None

What the base class provides so individual clients don’t reimplement it:

Feature	Detail
Session with retries	`_create_session()` mounts an `HTTPAdapter` with `urllib3` `Retry` — `max_retries` total, `backoff_factor=1`, retrying on `429, 500, 502, 503, 504` for `HEAD/GET/OPTIONS/POST/PUT`.
Default headers	`User-Agent: VulnMgmt-Enterprise/1.0`, `Accept`/`Content-Type: application/json`. Subclasses add auth headers on top.
Response handling	`_handle_response()` calls `raise_for_status()`, returns parsed JSON (or `{}` on empty body), and raises with the status + body text on error.
Verbose logging	`_log(message, level)` prints colorized status lines through `rich` when `verbose=True`.
Context manager	`__enter__`/`__exit__`/`close()` — use `with SomeClient(...) as c:` to guarantee the session is closed.

Every concrete client must implement three abstract methods:

@abstractmethod
def test_connection(self) -> bool: ...
@abstractmethod
def get_vulnerabilities(self, **kwargs) -> List[Dict[str, Any]]: ...
@abstractmethod
def get_assets(self, **kwargs) -> List[Dict[str, Any]]: ...

A typical concrete client translates its own constructor arguments into an IntegrationConfig, calls super().__init__(config, verbose), then adds its auth header to self.session.headers. For example, SentinelOneClient takes an api_token + console_url, builds the …/web/api/v2.1 base URL, and sets Authorization: ApiToken <token>.

A few clients are deliberately not subclasses of BaseIntegration because they don’t fit the asset/vuln shape: EPSSClient and ConnectWiseClient manage their own requests.Session directly.

Asset & vulnerability source clients

These are the clients that pull inventory and findings from security platforms, or push remediation tickets out.

SentinelOne — `sentinelone.SentinelOneClient`

Enterprise EDR client against the SentinelOne web/api/v2.1 console API.

client = SentinelOneClient(api_token="<jwt>", console_url="https://usea1-001-mssp.sentinelone.net")

Auth: Authorization: ApiToken <token>, timeout=60.
Covers agents/endpoints, threats, application inventory, vulnerabilities, activity logs, and group/site/policy management.
Typed models live in sentinelone/models.py (SentinelOneAgent, SentinelOneApplication, SentinelOneVulnerability, …).

Rapid7 InsightVM — `rapid7.Rapid7Client`

Client for the Rapid7 Insight platform (InsightVM vuln management, InsightIDR).

client = Rapid7Client(api_key="<key>", region="us")  # us, us2, us3, eu, ca, au, ap

Region-aware: REGION_ENDPOINTS maps each region to its https://<region>.api.insight.rapid7.com host; uses the v4 integration API.
Covers asset discovery, vulnerabilities, findings, and scan management. Typed models in rapid7/models.py.
Its raw output feeds the dedicated Rapid7 Vulnerabilities Excel sheet and the Rapid7ExcelReport generator (see Reporting & output).

Microsoft Defender for Endpoint — `defender.DefenderClient`

Client for the Defender for Endpoint API (exposed machines, CVE exposure, public/verified exploit flags). Feeds the Defender Vulnerabilities Excel sheet. Engine/CLI-only.

ConnectWise Manage (PSA) — `connectwise.ConnectWiseClient`

This is the PSA / ticketing integration (ConnectWise Manage), used to open and track remediation tickets — distinct from the webapp’s ConnectWise Automate (RMM) source. It authenticates with company id + public/private key + client id (loaded from env or a JSON file) against https://api-na.myconnectwise.net/…/apis/3.0.

The subpackage ships more than a raw client:

ConnectWiseClient — companies, contacts, configurations (assets), service tickets, notes, time entries, boards/statuses.
VulnTicketSync + VulnTicketSyncConfig / VulnTicketData — batch layer that turns findings into tickets, with an auto_create_threshold (e.g. HIGH).
convert_findings_to_vuln_data() — adapts report findings into ticket input.

Board and priority ids are captured as constants (BOARDS, PRIORITIES) so severity maps to a ConnectWise priority when a ticket is created.

Threat-intelligence feeds

The remaining clients enrich CVEs and indicators. The table below groups them by what they’re actually good for. “CVE feeds” work directly from a CVE id and drive the enrichment pipeline; “IOC feeds” work from IPs / URLs / hashes and are used for indicator lookups rather than CVE enrichment. See Threat intelligence & enrichment for how these are orchestrated.

Client	Feed	Provides	Auth / cost
`nvd.NVDClient`	NIST NVD	CVE details, CVSS v2/v3.0/v3.1 metrics, CWEs, references, CPE matches	Free; optional API key raises the rate limit (5→50 req/30s)
`cve_awg.CVEAWGClient`	CVE.org / MITRE CVE Services (`cveawg.mitre.org`)	Authoritative CVE record: references, affected products, problem types, assigner, publish date	Free, no key
`cvelist.CVEListClient`	CVE List V5 (GitHub raw)	Raw CVE JSON straight from the `cvelistV5` repo	Free, no key (git/raw access)
`cpe.CPEClient`	NIST CPE API 2.0	CPE dictionary lookups for product/version matching	Free; optional NVD key
`epss.EPSSClient`	FIRST EPSS	Probability a CVE is exploited in the next 30 days (score + percentile)	Free, no key
`mitre.MITREClient`	MITRE ATT&CK (STIX from GitHub)	Techniques & tactics (TTPs) mapped to a CVE	Free, no key (loads enterprise-attack dataset)
`otx.OTXClient`	AlienVault OTX	CVSS v2/v3, CWE, references, targeted products (CPE), pulses, threat actors & malware families	Free key (`X-OTX-API-KEY`); generous limits
`virustotal.VirusTotalClient`	VirusTotal API v3	File/URL/IP/domain reputation, multi-engine malware detection	Free key (`X-Apikey`); 4 req/min, 500/day
`shodan.ShodanClient`	Shodan	Internet-exposed hosts / exposure for an IP	Free tier key (limited, ~100 queries/mo)
`greynoise.GreyNoiseClient`	GreyNoise (v3)	Internet-scanner classification (benign vs malicious) for an IP	Free Community key; ~5,000 queries/mo
`abuseipdb.AbuseIPDBClient`	AbuseIPDB v2	IP reputation / abuse reports	Free key (`Key` header); 1,000 checks/day
`urlhaus.URLhausClient`	URLhaus (abuse.ch)	Malware-distribution URL tracking	Free, no key
`phishtank.PhishTankClient`	PhishTank	Phishing-URL verification	Free key
`spamhaus.SpamhausClient`	Spamhaus Intelligence API	IP/domain reputation blocklists	Free registration / key
`xforce.XForceClient`	IBM X-Force Exchange	CVE intel with exploit data, IP reputation, URL analysis, threat collections	Paid — requires Standard tier (Freemium blocks API access)

Notes on the feeds:

NVD is the primary CVE source. Without a key it is limited to 5 requests per 30-second window; with a free key that becomes 50. The engine enforces this with a sliding-window rate limiter and backs off on 403.
OTX is the richest single CVE feed and the enrichment default. A 2026 performance fix removed a slow separate pulse search — pulse data now comes back inside the CVE-details response, cutting per-CVE time from 30–127s to ~1–2s.
IOC feeds (VirusTotal, Shodan, GreyNoise, AbuseIPDB, URLhaus, Spamhaus, PhishTank) are marked not_applicable during CVE enrichment — they operate on indicators, not CVE ids, so the aggregator records them as available but skips them for CVE-only runs.
X-Force is fully implemented but gated behind IBM’s paid Standard tier; the Freemium tier the engine was tested against does not include API access.

What the webapp reuses

The legacy vulnmgmt package is the CLI/engine client library. The newer Lockstep VM webapp backend is a separate FastAPI service that implements its live sources as routers following the same client shape (see Integrations overview). The overlap in providers:

Provider	CLI/engine (`vulnmgmt.integrations`)	Webapp source
SentinelOne	`SentinelOneClient`	✅ yes
Rapid7 InsightVM	`Rapid7Client`	✅ yes
ConnectWise Automate (RMM)	—	✅ yes
ConnectWise Manage (PSA ticketing)	`ConnectWiseClient`	— (CLI-only)
Microsoft Defender	`DefenderClient`	— (CLI-only)
Threat-intel feeds (NVD, OTX, EPSS, …)	✅ all	— (enrichment is engine-side)

In short: SentinelOne and Rapid7 are the asset/vuln sources shared across both surfaces. Defender, the ConnectWise Manage PSA client, and the entire threat-intel feed set remain part of the CLI/engine.

CLI commands — how these clients are driven from the CLI.
Threat intelligence & enrichment — the enrichment pipeline.
Reporting & output — turning client data into reports.

Integrations library

The contract: BaseIntegration + IntegrationConfig

Asset & vulnerability source clients

SentinelOne — sentinelone.SentinelOneClient

Rapid7 InsightVM — rapid7.Rapid7Client

Microsoft Defender for Endpoint — defender.DefenderClient

ConnectWise Manage (PSA) — connectwise.ConnectWiseClient