relevant

Local-first security relevance for CVEs, advisories, IOCs, dependencies, logs, and service exposure.

relevant helps answer the question most scanners leave to humans:

Does this finding actually matter in this environment?

It is an open-source alpha for security engineers, AppSec teams, SOC analysts, platform teams, and curious builders who want evidence-first triage without sending code, logs, or inventories to a hosted service.

The package name is relsec, and the CLI is exposed as both relevant and relsec.

The Problem

Modern teams receive security findings faster than they can investigate them:

• A scanner says a dependency is vulnerable.
• A vendor advisory says a package needs urgent patching.
• A threat feed publishes IPs, domains, hashes, or other indicators.
• A SOC alert references activity that may or may not exist in local logs.
• A spreadsheet says a service is internet-facing, but nobody is sure which repo owns it.

The hard part is not seeing the alert. The hard part is proving whether it matters in your environment.

For example, imagine a critical upload-library CVE lands during a release freeze. A scanner flags multer somewhere in your monorepo. Before waking up every service owner, you need answers:

• Which service actually has the vulnerable version?
• Is that service internet-facing or internal-only?
• Is the vulnerable upload API used in source code?
• What evidence can be pasted into a ticket?
• What should be done next?

relevant turns that into a local evidence-gathering workflow instead of a meeting.

What This Tool Does

relevant reads local files and connects several pieces of security context:

Input	What it uses it for
Dependency manifests	Finds vulnerable package versions in package-lock.json, requirements.txt, and SBOM files.
Advisory data	Maps CVEs, GHSA IDs, or imported OSV records to affected packages, ranges, and risky symbols.
Service inventory	Understands whether a service is internet-facing, partner-facing, internal, or unknown.
Source code	Searches for vulnerable symbols or APIs that make a package actually reachable.
Logs	Matches IOCs against local log files, including gzip-compressed logs.
Reports	Produces terminal, JSON, JSONL, Markdown, and SARIF output for humans and automation.

It does not try to replace a scanner. It helps explain scanner output with local evidence.

Real-World Examples

Example 1: Triage A Dependency CVE

You receive a CVE for a vulnerable upload parser. Your scanner reports that multer exists somewhere in the repo.

Run:

relevant cve CVE-2026-41001 \
  --workspace examples/enterprise \
  --inventory examples/enterprise/security/inventory.json \
  --format markdown

relevant checks:

1. Is there a local advisory record for the CVE?
2. Which package and version range are affected?
3. Which services contain the vulnerable package version?
4. Are those services exposed?
5. Does source code reference vulnerable symbols such as upload.single or multer(?

Example result:

CVE-2026-41001: relevant (critical)

Evidence:
- Found multer 1.4.4 in services/checkout-api/package-lock.json.
- Reachable symbol upload.single in src/uploads.ts.
- checkout-api has public ingress: https://checkout.example.com/v1/receipts.

Recommended actions:
- Upgrade multer to >=1.4.5-lts.1.
- Restrict public upload endpoints until patched.
- Search access logs for unusual multipart upload paths.

That output gives AppSec, engineering, and incident response a shared artifact: vulnerable dependency, reachable code path, exposed service, and suggested next actions.

Example 2: Check Whether Threat Indicators Appear In Logs

A threat report publishes suspicious IPs and domains. You want to know whether those indicators appear in local Okta, proxy, CloudTrail, or server logs.

Run:

relevant ioc \
  --indicators examples/enterprise/security/cisa-aa26-141a.iocs \
  --logs examples/enterprise/security/logs/okta-auth-prod-2026-05-21.log \
  --logs examples/enterprise/security/logs/zscaler-web-prod-2026-05-21.log \
  --format json

Example result:

{
  "totalMatches": 2,
  "matches": [
    {
      "indicator": "203.0.113.77",
      "type": "ip",
      "line": 3
    },
    {
      "indicator": "evil-update.example",
      "type": "domain",
      "line": 1
    }
  ]
}

That helps a SOC analyst quickly move from "this IOC exists in a feed" to "this IOC appears in these local files on these lines."

Example 3: Build A Local Advisory File From OSV

When you want broader advisory coverage, import OSV records for dependencies found in your inventory:

relevant import osv \
  --workspace examples/enterprise \
  --inventory examples/enterprise/security/inventory.json \
  --output examples/enterprise/security/osv-advisories.json

After that, later CVE/GHSA checks can use the local file without calling OSV again:

relevant cve GHSA-example-id \
  --workspace examples/enterprise \
  --inventory examples/enterprise/security/inventory.json \
  --advisories examples/enterprise/security/osv-advisories.json

Status

This project is a developer preview. It is useful today for local experiments, demos, evidence collection, and early workflow design, but it is not a replacement for a vulnerability management platform, SIEM, SCA product, or incident response process.

What is ready:

• Deterministic local CVE relevance checks.
• Local IOC matching across plain and gzip logs.
• Service exposure inventory support.
• Reachability evidence from source-code symbol search.
• Explicit OSV advisory import.
• JSON, JSONL, Markdown, SARIF, and terminal output.
• Interactive command shell with profiles, history, completions, modules, and exports.
• Cross-platform CI for Node 20 and 22 on Linux, macOS, and Windows.

What is still evolving:

• OSV multi-affected and multi-range normalization.
• NVD and CISA KEV import.
• Deeper SBOM support.
• Docker image and Kubernetes exposure analysis.
• Full YARA and Sigma engines.
• More precise reachability analysis.

Design Goals

• Local-first by default.
• Evidence over opaque risk scores.
• Small enough to inspect.
• Useful in terminals, scripts, tickets, and CI jobs.
• Honest about uncertainty and limitations.

Quick Start

Install from npm:

npm install -g relsec
relevant --version

Run the bundled example after cloning the repository:

npm install
npm run build
node dist/cli.js cve CVE-2026-41001 --workspace examples/enterprise --inventory examples/enterprise/security/inventory.json --format markdown

Example output:

CVE-2026-41001: relevant (critical)
Multer multipart upload path traversal in file field handling: vulnerable package is reachable from an externally exposed service.

Quick Command Examples

Check whether a CVE matters locally:

npx relsec cve CVE-2026-41001 \
  --workspace examples/enterprise \
  --inventory examples/enterprise/security/inventory.json \
  --format markdown

Scan logs for indicators:

npx relsec ioc \
  --indicators examples/enterprise/security/cisa-aa26-141a.iocs \
  --logs examples/enterprise/security/logs/okta-auth-prod-2026-05-21.log \
  --logs examples/enterprise/security/logs/zscaler-web-prod-2026-05-21.log \
  --format json

Open the interactive console:

npx relsec

Commands

relevant cve <CVE-ID> --workspace . --inventory security/inventory.json --format json
relevant ioc --indicators indicators.txt --logs auth.log --logs proxy.log --format json
relevant import osv --workspace . --inventory security/inventory.json --output security/osv-advisories.json
relevant advisories
relevant version
relevant

Output formats:

• text
• json
• jsonl
• markdown
• sarif

Interactive Console

Run relevant with no arguments to open a REPL-style command shell. It keeps session context, supports command history, profiles, named workspaces, path completion, and module-style workflows.

rel > set workspace examples/enterprise
rel > set inventory examples/enterprise/security/inventory.json
rel > scan CVE-2026-41001
rel > evidence
rel > actions
rel > export markdown finding.md
rel > set indicators examples/enterprise/security/cisa-aa26-141a.iocs
rel > ioc examples/enterprise/security/logs/okta-auth-prod-2026-05-21.log
rel > exit

Module workflow:

rel > use cve
rel(cve) > set cve CVE-2026-41001
rel(cve) > show options
rel(cve) > run
rel(cve) > back
rel > show modules

Available modules:

• cve: dependency CVE relevance
• ioc: IOC log matching
• exposure: externally exposed services
• sbom: dependency inventory
• secrets: obvious local secret patterns
• cloudtrail: CloudTrail triage heuristics
• auth: identity/auth log triage heuristics
• yara: simple YARA literal rules
• sigma: simple Sigma keyword rules

Example Environment

examples/enterprise is a dummy environment for testing and demos:

• checkout-api: internet-facing Node service with vulnerable reachable multer upload usage.
• ml-worker: internal Python worker with a vulnerable package version but no vulnerable parser reachability.
• Okta, Zscaler, and AWS CloudTrail-style logs.
• CISA-style IOC list.
• Service exposure inventory.

No real customer data is included.

Privacy Model

Normal scans are local-first:

• CVE analysis reads local manifests, inventories, source files, SBOMs, and advisory files.
• IOC analysis reads local logs directly.
• Reports are written locally.
• No telemetry is collected.
• No cloud API is used during normal scans.

The import osv command is the one intentional networked workflow. It sends discovered package names, ecosystems, and versions to the configured OSV API endpoint, then writes normalized advisory records to a local file for later offline use.

Limitations

This is an alpha project with deliberate constraints:

• CVE relevance depends on advisory quality, manifest coverage, inventory accuracy, and symbol search.
• Reachability is currently evidence-oriented string matching, not full program analysis.
• OSV import does not yet preserve every multi-affected or multi-range advisory shape.
• YARA support handles literal string rules, not the full YARA language.
• Sigma support handles simple keyword-style rules, not a full Sigma backend.
• CloudTrail and auth modules are deterministic triage heuristics, not SIEM replacements.
• Secret detection is heuristic and should not replace dedicated secret scanning.
• Generated reports may contain sensitive local evidence.

Development

npm install
npm run typecheck
npm test
npm run build

Full local release gate:

npm run release:check
npm run pack:dry-run

CI runs typecheck, tests, build, and package dry-run on Node 20 and 22 across Linux, macOS, and Windows.

Contributing

Contributions are welcome. Good first areas:

• More fixture environments.
• Additional advisory import formats.
• Better SBOM parsing.
• More report templates.
• Safer scanner heuristics.
• Documentation and examples.

Please read CONTRIBUTING.md before opening a pull request.

Roadmap

• Preserve OSV multi-affected and multi-range records.
• Add NVD and CISA KEV import.
• Expand CycloneDX and SPDX support.
• Add Docker image and Kubernetes manifest exposure analysis.
• Add GitHub and Jira export templates.
• Add optional local summarization through Ollama or LM Studio.
• Improve reachability analysis while keeping the tool local-first.

Security

See SECURITY.md for the security model, network behavior, sensitive data guidance, and vulnerability reporting notes.

License

MIT. See LICENSE.