RajaMuhammadAwais/RISKX: RISKX - Research-first enterprise cyber-risk CLI: attack-surface discovery, vulnerability intelligence and risk prioritization. Evidence-backed, no guessing, offline-capable. · GitHub

+--------------------------------+
|   ____  ___ ____  _  ____  __ |
|  |  _ \|_ _/ ___|| |/ /\ \/ / |
|  | |_) || |\___ \| ' /  \  /  |
|  |  _ < | | ___) | . \  /  \  |
|  |_| \_\___|____/|_|\_\/_/\_\ |
+--------------------------------+

RISKX is a command-line tool for continuous threat-exposure management (CTEM). It discovers your assets passively, enriches them with verified vulnerability intelligence, scores risk with a deterministic evidence-backed model, ranks attack paths, validates findings safely, and produces executive reports and machine-readable exports — all with mandatory evidence attached to every finding.

It follows the CISA CTEM lifecycle — Discover → Prioritize → Remediate → Validate — and is grounded exclusively in verified primary sources: CISA, NIST NVD, FIRST, MITRE, OWASP, and OSV.

Full end-to-end walkthrough of every RISKX feature (init → doctor → config → discover --delta → assets → vuln → prioritize → risk → delta → export (SARIF / CSV / JSONL) → report → graph → explain → attack-path → policy → validate → feed → cloud → serve → mcp → continuous → scan), captured live against a real build of v0.4.0.

THE NO-GUESSING RULE. Facts, inferences, and recommendations are separated in the data model. Detection without evidence is reported as insufficient confidence — never a fabricated finding. Inferred edges and findings are explicitly labeled and never presented as confirmed. Stale feeds are marked STALE, never silently dropped. Feed failures raise explicit errors, never "no data".

This is a non-commercial tool: see NON_COMMERCIAL.md and the LICENSE (CC BY-NC-ND 4.0). You are free to use, build, and share it for research, education, and personal defense — commercial use requires a separate license from the author.

Most security tools present conclusions as facts. RISKX presents conclusions with their evidence: every finding carries what was observed, which source said so, when it was checked, and how confident the tool is. This makes the output audit-ready — an analyst can trace any line of a report back to the observation that produced it.

These updates follow the research-backed roadmap (P0: agent data layer, CT-log attack-surface depth, agentic AI consumers): agents integrate over the canonical JSON evidence API instead of building their own scanners. Full flag tables are in the Flags Reference.

The v0.4.0 release implements the evidence-based prioritization layer of the research roadmap: enrichment data must be offline-verifiable, provenance-tagged, and stale-marked before any finding can be ranked on it — no live-only lookups, no inferred exploit claims. Full flag tables are in the Flags Reference.

# 0. Pull verified feeds into the local offline cache (the only network touch-point)
riskx feed sync                        # sync KEV catalog
riskx feed sync --epss CVE-2021-44228,CVE-2024-3094   # also pull EPSS for listed CVEs

# Inspect the cache offline (no network)
riskx feed list
riskx feed list --stale --json

# Rank findings by documented exploit evidence (offline, deterministic)
riskx prioritize                       # requires --data store + synced cache
riskx prioritize --data ./riskx.db --json

# Delta scanning: snapshot each run, report changes vs the prior run
riskx discover example.com --data ./riskx.db --delta
riskx discover example.com --data ./riskx.db --delta   # second run shows new/gone/changed assets vs the first

# Replay any earlier pair of stored snapshots
riskx delta --data ./riskx.db --json
riskx delta --data ./riskx.db --since snap-abcdef1234567890

RISKX is written in pure Go with a pure-Go SQLite driver (no CGo), so the same binary model builds and runs on every supported platform. Compatibility was verified on Ubuntu 24.04 (linux/amd64); other platforms use the identical code path.

No Go toolchain required. The recommended installation pulls the pre-built binary for your OS and CPU architecture directly from the official GitHub Releases — the installer never clones the repository, downloads only one binary plus its checksums file, verifies the SHA-256 checksum before installing, and installs into a user-writable directory (~/.local/bin on Linux/macOS, %USERPROFILE%\.local\bin on Windows; created automatically if it does not exist). No sudo, no admin rights required.

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/RajaMuhammadAwais/RISKX/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/RajaMuhammadAwais/RISKX/main/install.ps1 | iex

The installer detects your OS and CPU architecture, resolves the latest stable release (prereleases are never installed automatically), downloads the matching binary from the official GitHub Release, verifies its SHA-256 checksum against the release's checksums.txt (on failure the file is deleted and nothing is installed), and places it in your user bin directory. If that directory is not on your PATH, the installer prints the exact command to add it.

Install a specific release:

RISKX_VERSION=v0.4.0 curl -fsSL https://raw.githubusercontent.com/RajaMuhammadAwais/RISKX/main/install.sh | sh   # Linux / macOS
$env:RISKX_VERSION="v0.4.0"; irm https://raw.githubusercontent.com/RajaMuhammadAwais/RISKX/main/install.ps1 | iex   # Windows

Override the install directory (either platform):

RISKX_BIN_DIR=/opt/riskx/bin curl -fsSL https://raw.githubusercontent.com/RajaMuhammadAwais/RISKX/main/install.sh | sh   # Linux / macOS
$env:RISKX_BIN_DIR="C:\Tools\RISKX"; irm https://raw.githubusercontent.com/RajaMuhammadAwais/RISKX/main/install.ps1 | iex   # Windows

What the installer does — and does not do: it resolves a release, downloads exactly two files (the binary and checksums.txt) over HTTPS, verifies the SHA-256 checksum, copies the verified binary to the user bin directory, and prints the installed version. It never clones the repository, downloads unrelated files, modifies unrelated user files, installs persistence, creates services or scheduled tasks, touches firewall rules, or collects telemetry. A checksum failure deletes the downloaded file and exits with a clear error — an unverified binary is never silently installed.

Download the binary that matches your platform from Releases alongside checksums.txt, verify it, then install:

# Linux example (adjust OS/arch to match your platform)
wget https://github.com/RajaMuhammadAwais/RISKX/releases/download/v0.4.0/riskx_linux_amd64
wget https://github.com/RajaMuhammadAwais/RISKX/releases/download/v0.4.0/checksums.txt
sha256sum -c <(grep riskx_linux_amd64 checksums.txt)
chmod +x riskx_linux_amd64 && mv riskx_linux_amd64 ~/.local/bin/riskx

Go 1.25 or newer is required. The binary is built from source and lands in $(go env GOPATH)/bin (default ~/go/bin):

go version

Install Go if not present (Ubuntu / Debian, latest versions):

# Install Go 1.25+ if not present
sudo apt update
sudo apt install -y golang-go   # or download latest from https://go.dev/dl/

# Verify
go version

Fedora:

sudo dnf install -y golang
go version

Arch Linux:

sudo pacman -S go
go version

macOS (Homebrew):

brew install go
go version

Windows (Scoop):

scoop install go
go version

Then build from source or use go install:

go install github.com/RajaMuhammadAwais/RISKX/cmd/riskx@latest

git clone https://github.com/RajaMuhammadAwais/RISKX.git
cd RISKX
go build -o riskx ./cmd/riskx

# Move into your PATH
sudo mv riskx /usr/local/bin/    # Linux / macOS
# or on Windows, move riskx.exe anywhere on %PATH%

Cross-compiling for another OS works identically:

GOOS=windows GOARCH=amd64 go build -o riskx.exe ./cmd/riskx
GOOS=darwin  GOARCH=arm64 go build -o riskx ./cmd/riskx
GOOS=linux   GOARCH=arm64 go build -o riskx ./cmd/riskx

Each release publishes these pre-built binaries:

Every release also ships checksums.txt with SHA-256 hashes for all assets. Release binaries inject version, commit, build date, and platform via Go linker flags — visible in the version output.

riskx version
riskx doctor          # self-diagnoses your environment

The CTEM loop in five commands:

# 1. Discover assets (passive, read-only); --ct adds certificate-transparency enumeration
riskx discover example.com --ct --data ./riskx.db

# 2. Pull verified feeds into the offline cache (KEV / EPSS) — do this first
riskx feed sync
riskx feed sync --epss CVE-2021-44228,CVE-2024-3094

# 3. Enrich vulnerabilities (CISA KEV, NVD CVSS, FIRST EPSS, OSV aliases)
riskx vuln CVE-2021-44228 --data ./riskx.db

# 3b. Rank what to fix first by documented exploit evidence (offline, deterministic)
riskx prioritize --data ./riskx.db

# 4. Score risk deterministically
riskx risk --data ./riskx.db

# 5. Validate safely (read-only checks, no exploitation)
riskx validate tls example.com --data ./riskx.db

# 6. Report + export for your SOC / ticketing system
riskx report summary --data ./riskx.db
riskx export sarif  --data ./riskx.db > riskx.sarif   # GitHub/SonarQube compatible
riskx export csv    --data ./riskx.db > riskx.csv
riskx export jsonl  --data ./riskx.db > riskx.jsonl

# 7. Optional: serve the evidence store as a read-only JSON API (agents / BI / SIEM)
riskx serve --data ./riskx.db --listen 127.0.0.1:8890 --key "$RISKX_API_KEY"

# 8. Optional: LLM explanation of a verified finding (off by default)
riskx explain --finding <id> --data ./riskx.db   # needs llm.enabled + RISKX_LLM_API_KEY

Run everything at once:

riskx scan example.com --mode passive

Commands marked future phase (identity, agent, mcp) are scaffolded and reserved; they print a clear status message and do nothing silently.

The feed cache is the only point where RISKX touches upstream catalogs; every other command reads the cached, provenance-tagged copy. Failed fetches keep the last usable cache and report the failure explicitly — data is marked STALE, never silently removed.

Requires both a populated evidence store (findings with CVE references) and a synced feed cache (riskx feed sync). Ranking uses documented public exploitation evidence only (rank-v1): KEV membership beats EPSS≥0.5, both beat no-evidence; ties are broken by severity then finding ID. Offline and deterministic.

Snapshots are content-addressed — identical runs reproduce identical snapshot IDs — so delta reports stay reproducible and audit-grade: every change carries the SHA-256 hashes of both compared contents and the exact fingerprint fields that drifted. With only one stored snapshot the first run prints a confirmation message and stores the snapshot; subsequent runs compare against it.

Without a key the API refuses all authenticated endpoints (401). Serves: GET /v1/assets, /v1/findings, /v1/evidence, /v1/relationships, /v1/risk, /v1/health, /v1/metadata.

Requires llm.enabled: true in config plus RISKX_LLM_API_KEY and llm.model. The LLM only explains verified native content — it never sets severity, confidence, or classification.

Passive discovery with JSON output:

riskx discover example.com --json

Bulk targets from a file:

riskx discover --file targets.txt --records A,MX,TXT --ports 80,443,8080

Validate a TLS configuration safely:

riskx validate tls example.com --json

Verify DNS against expected values (useful in CI):

riskx validate dns example.com --dns-want 93.184.216.34 --ci --preapprove

AWS cloud discovery (read-only; requires AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY):

riskx cloud discover all
riskx cloud discover --action buckets

Policy check for CI pipelines (exit code 0/1/2):

riskx policy check --file policy.yaml
echo $?

Every security artifact in RISKX carries provenance. Findings separate FACT (observation + evidence items), INFERENCE (confidence and status), and RECOMMENDATION (remediation, never presented as fact). Attack-graph edges carry one of four statuses:

• observed — directly measured in the current scan
• inferred — plausible from evidence, explicitly never confirmed
• potential — theoretically possible, no evidence yet
• validated — confirmed via an approved validation step

Feeds declare freshness; data older than its allowed age is marked stale.

Print all versions at once with riskx version.

cmd/riskx/                 CLI entry point and command tree
internal/core/             config, log, errs, mode, output, idgen, runner
internal/discovery/        dns, http, tls, rdap passive-discovery engines
internal/vulnerability/    ingest (KEV/NVD/EPSS/OSV), normalize, findings
internal/risk/             risk-v1 deterministic scoring engine
internal/graph/            graph-v1 attack graph (BFS, Dijkstra, centrality)
internal/policy/           YAML policy evaluation
internal/reporting/        report-v1 summary + SARIF 2.1.0 / CSV / JSONL export
internal/validate/         safe read-only DNS/TLS/HTTP validation
internal/cloud/            cloud-v1 AWS read-only discovery (SigV4)
internal/storage/          storage-v1 SQLite persistence
internal/evidence/         source-metadata and confidence typing
pkg/models/                canonical versioned data model
pkg/plugins/               plugin interfaces and registry
.github/workflows/         CI: test/build, lint, staticcheck, govulncheck

go build ./...          # compile everything
go vet ./...            # static analysis
go test ./... -short    # unit + fixture tests (live feeds skipped)
go test ./...           # includes live feed integration tests
go test ./... -race     # race detector (pure-Go SQLite driver; no gcc needed)
go test -bench=. -run=^$ ./internal/risk ./internal/vulnerability/ingest

Measured on live hardware (Ubuntu 24.04, linux/amd64):

RISKX is non-commercial open-source software authored by Raja Muhammad Awais.

• Code, documentation, and research artifacts: CC BY-NC-ND 4.0 — free to use, build, and share for non-commercial purposes with attribution; no commercial use and no derivative works without permission.
• Commercial licensing: contact the author (see NON_COMMERCIAL.md).
• Third-party data: CISA, NIST NVD, FIRST EPSS, MITRE, OWASP, and OSV data carry their own licenses and attribution requirements, which RISKX reproduces verbatim in its outputs.

RAJA MUHAMMAD AWAIS — Cyber Security Researcher Built with a research-first methodology: every capability grounded in verified primary sources, every output evidence-backed.

If this project helps you, star it on GitHub — and remember: scan only what you own or are authorized to test.