Integrating External Feeds (KEV & EPSS)

Relevant source files

The following files were used as context for generating this wiki page:

• core/exploit_signals.py
• core/stage_runner.py
• risk/feeds/epss.py
• risk/feeds/kev.py
• artifacts/upstream_doc_index.json
• artifacts/upstream_symbol_index.json
• tests/test_exploit_signals.py

The Aldeci platform integrates external threat intelligence feeds to enrich vulnerability data and enable risk-based prioritization. Specifically, it uses CISA's Known Exploited Vulnerabilities (KEV) catalog and the Exploit Prediction Scoring System (EPSS) from FIRST.org. This integration allows the system to correlate exploit probability and active exploitation status with internal findings, which is a core part of the platform's "Risk-first posture".

This enriched data is primarily consumed during the operate stage of the processing pipeline to calculate operational risk and is also used by the ExploitSignalEvaluator to score exploitability. The entire process is designed to be automated, with feeds being periodically refreshed and cached locally for performance and reliability.

Sources: artifacts/upstream_doc_index.json, core/stage_runner.py:410-420

Architecture and Data Flow

The system employs a modular architecture for fetching, storing, and consuming exploit intelligence. An ExploitFeedRefresher component is responsible for downloading the latest data from upstream sources (CISA for KEV, FIRST.org for EPSS). This data is then saved to the local filesystem in a structured JSON format. Downstream components, such as the StageRunner, read these cached files to enrich their analysis.

The following diagram illustrates the high-level data flow for external feeds.

Feed Refresh Mechanism

The process of updating the local feed caches is managed by components within core/exploit_signals.py.

Sources: artifacts/upstream_symbol_index.json:symbols.core/exploit_signals.py

Components

Component	Description	Source File
ExploitFeedRefresher	A class responsible for enriching records by refreshing exploit intelligence feeds.	core/exploit_signals.py
refresh_exploit_feeds	The main function that orchestrates the fetching of all configured exploit feeds.	core/exploit_signals.py
_refresh_named_feed	A helper function to refresh a specific, named feed.	core/exploit_signals.py
_start_scheduler	A function that suggests the presence of a scheduler to run the refresh process periodically.	core/exploit_signals.py
risk/feeds/kev.py	A dedicated module to fetch and process the CISA KEV catalog.	risk/feeds/kev.py
risk/feeds/epss.py	A dedicated module to fetch and process the EPSS scores.	risk/feeds/epss.py

Refresh Sequence

The refresh process is initiated to update the local kev.json and epss.json files. The ExploitFeedRefresher coordinates this by invoking the specialized modules for each feed.

The following sequence diagram shows the feed refresh process.

Data Storage

The fetched and processed data from the KEV and EPSS feeds are stored in the data/feeds/ directory. This local caching strategy ensures that the pipeline can run without a live internet connection and improves performance by avoiding repeated downloads.

Sources: core/stage_runner.py:412-413, artifacts/upstream_doc_index.json

Feed File Formats

File	Path	Description	Structure Example
KEV Feed	data/feeds/kev.json	Contains a list of known exploited vulnerabilities from CISA. The _process_operate method specifically looks for a top key.	{ "top": ["CVE-2021-44228", ...] }
EPSS Feed	data/feeds/epss.json	Contains EPSS scores for CVEs. The _process_operate method also looks for a top key containing records with CVEs and scores.	{ "top": [{"cve": "CVE-2021-44228", "score": 0.97}, ...] }

Sources: core/stage_runner.py:412-420, artifacts/upstream_doc_index.json

Consumption and Usage

The cached KEV and EPSS data are used by different parts of the system to assess risk.

operate Stage Processing

The _process_operate method within the StageRunner class is a primary consumer of the feed data. During the operate stage, it loads kev.json and epss.json to identify active threats and calculate an operate_risk_score.

The following diagram illustrates this consumption flow.

The method reads the JSON files and extracts relevant information to be included in the operate.snapshot.json output.

# Source: core/stage_runner.py:410-420
    def _process_operate(
        # ...
    ) -> Mapping[str, Any]:
        # ...
        build_report = self._read_optional_json(context.outputs_dir / "build.report.json") or {}
        kev_feed = self._read_optional_json(Path("data/feeds/kev.json")) or {}
        epss_feed = self._read_optional_json(Path("data/feeds/epss.json")) or {}
        kev_hits = []
        epss_records = []
        risk_components = build_report.get("risk_flags", []) if isinstance(build_report, Mapping) else []
        for flag in risk_components:
            if isinstance(flag, Mapping) and "log4j" in str(flag.get("purl", "")).lower():
                kev_hits.append("CVE-2021-44228")
                epss_records.append({"cve": "CVE-2021-44228", "score": 0.97})
                break

Sources: core/stage_runner.py:410-420

Exploit Signal Evaluation

The ExploitSignalEvaluator class is another key consumer. Its purpose is to evaluate vulnerabilities against the loaded KEV and EPSS data to determine their exploitability. This is confirmed by tests such as test_exploit_signal_evaluator_matches_boolean_and_probability. The evaluator uses the helper functions load_latest_kev_feed and load_latest_epss_feed to access the cached data.

Sources: artifacts/upstream_symbol_index.json:symbols.core/exploit_signals.py.ExploitSignalEvaluator, tests/test_exploit_signals.py

Summary

The integration of KEV and EPSS feeds is a critical capability of the Aldeci platform, providing essential context for vulnerability management. By automating the refresh and consumption of this data, the system ensures that its risk scoring and decision-making processes are informed by the latest real-world threat intelligence, enabling teams to prioritize the most critical threats effectively.

Sources: artifacts/upstream_doc_index.json