feat(output-types): tag known-exploited vulnerabilities with kev (#1319)

[juandresrodca]

Closes #1319.

Adds kev tagging for known-exploited vulnerabilities, following the recipe in the issue.

notes

• Lazy + memoized, not fetched at import time, so offline mode and tests don't hit
  the network. Fails open: offline / download error / malformed feed → empty set, so
  tagging is always a safe no-op.
• Matches self.id against the CVE list per the recipe; matching CVEs found in
  references / extra_data could be a follow-up.
• Happy to wire the fetch into startup explicitly instead of lazy-on-first-use, or to
  expose the URL / a toggle in Config, if you'd prefer.

---

• secator/kev.py (new): downloads the CISA KEV feed once
  (https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json),
  cached to the data dir via the existing download_file() helper (same path as
  wordlists/payloads), and exposes a memoized get_kev_cve_ids() returning the set
  of KEV CVE ids — built as {v['cveId'] for v in KEV_DATA['vulnerabilities']}.
• secator/output_types/vulnerability.py: post_init tags a vuln with kev
  when its id (the CVE id) is in the KEV set. Done here so it applies to vulns from
  every task, not just CVE-enriched ones — which lights up the already-documented
  vulnerability.tags ~= 'kev' cheatsheet query.
• tests/unit/test_kev.py (new): unit tests (no network — the loader is patched).

Testing

secator test unit --test test_kev (6 passed); flake8 clean. Existing
test_output_types still green.

Summary by CodeRabbit

• New Features

  • Vulnerabilities associated with CISA Known Exploited Vulnerabilities are now automatically marked with a kev tag.
  • CVE matching is case-insensitive, and duplicate tags are avoided.
  • The latest KEV catalog is downloaded and cached for efficient reuse.

• Bug Fixes

  • Vulnerability processing now continues safely when the catalog is unavailable, malformed, or a vulnerability has no identifier.

[coderabbitai]

Walkthrough

Adds lazy CISA KEV catalog loading with process-level caching, extracts normalized CVE identifiers, and automatically adds the kev tag to matching vulnerabilities. Unit tests cover matching, unavailable catalogs, duplicate tags, and missing IDs.

Changes

KEV vulnerability tagging

Layer / File(s)	Summary
KEV catalog loading and caching secator/kev.py	Defines the CISA feed URL, lazily loads and caches upper-cased CVE IDs, and returns an empty set when loading or parsing fails.
Vulnerability tagging and validation secator/output_types/vulnerability.py, tests/unit/test_kev.py	Tags matching vulnerabilities during initialization and tests case-insensitive matches, missing entries, duplicate prevention, unavailable catalogs, and missing IDs.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Vulnerability
  participant KEVLookup
  participant CISACatalog
  Vulnerability->>KEVLookup: initialize and request KEV identifiers
  KEVLookup->>CISACatalog: load catalog JSON
  CISACatalog-->>KEVLookup: return CVE records
  KEVLookup-->>Vulnerability: return cached CVE set
  Vulnerability->>Vulnerability: append kev for matching ID

Loading

Possibly related issues

• #385: Directly matches the added CISA KEV lookup and kev tagging behavior.

Poem

I’m a rabbit with a catalog bright,
Tagging CVEs by day and night.
Cache the feed, hop past the rain,
Match a CVE, add kev again.
No ID? I simply chew hay.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes adding KEV tags to vulnerabilities, matching the primary change.
Linked Issues check	✅ Passed	The changes download and cache the KEV feed, extract CVE IDs, and tag matching initialized vulnerabilities as required by issue #1319.
Out of Scope Changes check	✅ Passed	All changes are directly related to KEV catalog loading, vulnerability tagging, and focused unit test coverage.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/unit/test_kev.py (1)

16-46: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add direct loader and cache tests.

These tests mock _load_kev_cve_ids(), so regressions in download_file() delegation, JSON parsing, malformed-feed fallback, or memoization still pass. Add focused get_kev_cve_ids() tests that patch secator.kev.download_file and verify a valid fixture, malformed JSON fallback, and a single loader call across two lookups.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/unit/test_kev.py` around lines 16 - 46, Add focused tests for
get_kev_cve_ids() that mock secator.kev.download_file and cover valid JSON
parsing, malformed-feed fallback to an empty set, and memoization by asserting
two lookups trigger only one download. Keep the existing Vulnerability tag tests
unchanged and reset the cache between cases so each test remains isolated.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/unit/test_kev.py`:
- Around line 16-46: Add focused tests for get_kev_cve_ids() that mock
secator.kev.download_file and cover valid JSON parsing, malformed-feed fallback
to an empty set, and memoization by asserting two lookups trigger only one
download. Keep the existing Vulnerability tag tests unchanged and reset the
cache between cases so each test remains isolated.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8f376e03-8136-4503-a4dd-b6bf6d3245c9

📥 Commits

Reviewing files that changed from the base of the PR and between 8a97c79 and c9c1e05.

📒 Files selected for processing (3)

• secator/kev.py
• secator/output_types/vulnerability.py
• tests/unit/test_kev.py

[juandresrodca]

Let me know if you need any explain on the code or modify it

[ocervell]

Hi @juandresrodca ! Sorry I just returned from vacations.
This is really great ! I wanted to do it when coming back actually.
Give me a little time to review and it will go into the next release, thanks a lot for taking the time to make a PR ;)