Truesignal

TrueSignal

Install • Quickstart • Features • CLI Reference • MCP Server • Compare • FAQ

A personal OSINT/security intelligence feed with a no-fabrication guarantee verified by 22 automated tests: every connector's failure path returns real cached data or nothing, never an invented data point.

Install

TrueSignal ships as two independent, equally first-class packages -- pick whichever fits your toolchain, or install both:

npm (JS/TS CLI):

npx truesignal-cli init

truesignal-cli is published on npm (see the badge above). To build from source instead:

git clone https://github.com/RudrenduPaul/truesignal.git && cd truesignal && npm install && npm run build && node dist/cli.js init

Requires Node.js 18.17 or later. Both install paths verified working on 2026-08-03.

For repeat use, npm link after building gives you the truesignal command directly instead of typing node dist/cli.js.

pip (Python library + CLI):

pip install truesignal-cli

A genuine, independent Python port -- not a wrapper around the Node binary -- with the same five connectors, the same provenance-stamping guarantee, and the same init/feed/verify CLI surface. See python/README.md for the Python-specific quickstart. Both packages are maintained together; neither is deprecated in favor of the other.

$ truesignal init

truesignal connector status:

[ready] CISA Known Exploited Vulnerabilities (cisa-kev) -- no configuration needed [not configured] Cloudflare Radar (cloudflare-radar) -- set CLOUDFLARE_RADAR_API_TOKEN [not configured] Reddit (reddit) -- set REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET [not configured] Telegram (telegram) -- set TELEGRAM_BOT_TOKEN [ready] GDELT (gdelt) -- no configuration needed

2/5 connectors ready. Set the missing environment variables above to enable the rest. See .env.example. Next: run "truesignal feed" to see your feed now.

$ truesignal feed --source cisa-kev

[live] cisa-kev: CVE-2023-4346: KNX Association KNX Protocol Connection Authorization Option 1 Overly Restrictive Account Lockout Mechanism Vulnerability -- https://nvd.nist.gov/vuln/detail/CVE-2023-4346 -- 1d ago [live] cisa-kev: CVE-2026-46817: Oracle E-Business Suite Improper Privilege Management Vulnerability -- https://nvd.nist.gov/vuln/detail/CVE-2026-46817 -- 1d ago [live] cisa-kev: CVE-2026-15410: SonicWall SMA1000 Appliances Code Injection Vulnerability -- https://nvd.nist.gov/vuln/detail/CVE-2026-15410 -- 2d ago

This is a real, unedited capture (npm run build && node dist/cli.js init && node dist/cli.js feed --source cisa-kev), against the live CISA-KEV catalog, on 2026-07-15. CVE ids, urls, and ages are real.

Features

• 5 source connectors behind one common Connector interface (src/truesignal/types.ts): CISA Known Exploited Vulnerabilities, Cloudflare Radar, Reddit (official OAuth API), Telegram (official Bot API), and GDELT.
• Provenance stamp on every item -- a real source URL, a real upstream timestamp (never new Date()), and an explicit live or fallback status. A fallback item also carries fallbackAgeSeconds, so you always know exactly how stale what you're looking at is.
• No-fabrication guarantee enforced in code. No connector contains Math.random(), a fake-data library, or a "rewrite the timestamp to now" path. A dedicated test suite (src/truesignal/provenance/no-fabrication.test.ts, 22 tests) proves this for every connector's live, fallback, and empty-cache-failure paths, and a static check scans every connector source file for forbidden patterns.
• Agent-native output. Every subcommand has a --json flag with a stable, documented shape and real, distinct exit codes, so an agent can parse a result without scraping human-formatted text.
• Zero-key startup. CISA-KEV and GDELT need no API key at all; truesignal init and truesignal feed work the moment the CLI is installed.
• Self-hosted, BYO keys, no telemetry by default. truesignal reads credentials only from real environment variables, and it doesn't auto-load .env files or phone home.
• Extensible by design. Adding a new source (NVD, Shodan, VirusTotal, ...) is a new file implementing Connector and one line in connectors/index.ts -- never a change to the CLI or provenance layer. See CONTRIBUTING.md.

Quickstart

truesignal init

truesignal feed

init tells you which connectors are ready right now (CISA-KEV and GDELT need nothing) and which environment variables are still missing for the rest. feed pulls from every configured connector. Real, unedited output from the two zero-config sources:

[live] cisa-kev: CVE-2023-4346: KNX Association KNX Protocol Connection Authorization Option 1 Overly Restrictive Account Lockout Mechanism Vulnerability -- https://nvd.nist.gov/vuln/detail/CVE-2023-4346 -- 1d ago

[fallback, 37m old] gdelt: White House launches AI-backed Gold Eagle initiative for cybersecurity vulnerability coordination -- https://www.scworld.com/brief/white-house-launches-ai-backed-gold-eagle-initiative-for-cybersecurity-vulnerability-coordination -- 2h ago

That second line is real, too: on this run GDELT's live fetch didn't complete, so truesignal showed the last real GDELT items it had actually fetched, honestly labeled fallback with their real age, instead of being silently repainted as current.

To enable the other three sources (Cloudflare Radar, Reddit, Telegram), copy .env.example to .env, fill in real free credentials, then export them into your shell -- truesignal doesn't auto-load .env files:

set -a && source .env && set +a

CLI command reference

Generated directly from this build's actual --help output (node dist/cli.js --help and each subcommand's --help).

truesignal

Usage: truesignal [options] [command]

A provenance-first OSINT/security intelligence feed. Every item carries a real source URL, a real timestamp, and an explicit live/fallback flag -- never a fabricated or silently-replayed data point.

Options: -V, --version output the version number -h, --help display help for command

Commands: init [options] Check which connectors are ready to use right now and which environment variables are still needed for the rest. CISA-KEV and GDELT need no configuration -- truesignal works with zero setup for those two sources. feed [options] Pull the current feed from every configured connector, or one connector with --source. Prints human-readable output by default; use --json for a stable, agent-parseable schema. verify [options] Re-fetch the source connector named in and confirm whether that item still resolves to real, live provenance, has fallen back to cached data, or can no longer be found. help [command] display help for command

truesignal init [--json]

Exit code 0 if at least one connector is usable, 2 if none are (shouldn't happen -- CISA-KEV and GDELT need no configuration).

truesignal feed [--source ] [--json]

--source <name>  only pull from this connector, e.g. cisa-kev, gdelt

--json print machine-readable JSON instead of human-readable text

Exit codes: 0 success, 2 no connectors configured to run, 3 every configured connector's fetch failed with no data to show.

--json output is a stable, documented FeedItem[] shape. Real capture:

{

"items": [ { "id": "cisa-kev:CVE-2023-4346", "source": "cisa-kev", "title": "CVE-2023-4346: KNX Association KNX Protocol Connection Authorization Option 1 Overly Restrictive Account Lockout Mechanism Vulnerability", "url": "https://nvd.nist.gov/vuln/detail/CVE-2023-4346", "timestamp": "2026-07-15T00:00:00.000Z", "status": "live" } ] }

truesignal verify [--json]

![truesignal verify cisa-kev:CVE-2023-4346 confirming live provenance, followed by truesignal feed --source cisa-kev --json printing the stable FeedItem[] JSON schema, run via npx truesignal-cli](./docs/usage.gif)

Re-fetches the source named in (format : , e.g. cisa-kev:CVE-2023-4346) and confirms whether that item still resolves to real, live provenance, has fallen back to cached data, or can no longer be found. Real capture:

$ truesignal verify cisa-kev:CVE-2023-4346

cisa-kev:CVE-2023-4346: LIVE -- https://nvd.nist.gov/vuln/detail/CVE-2023-4346 -- 2026-07-15T00:00:00.000Z

Exit codes: 0 found and live/fallback, 1 re-fetched successfully but the item is gone, 2 the connector isn't configured, 3 the re-fetch failed, 4 the item id is malformed or names an unknown source.

MCP Server

TrueSignal ships a Model Context Protocol (MCP) server, so an MCP-compatible agent runtime (Claude Desktop, Claude Code, or any other MCP client) can call TrueSignal directly instead of shelling out to the CLI and parsing text.

pip install "truesignal-cli[mcp]"

Add it to your Claude Desktop config (claude_desktop_config.json):

{

"mcpServers": { "truesignal": { "command": "truesignal-mcp" } } }

The server exposes a single tool, run(args: list[str]), that shells out to the installed truesignal CLI with the given arguments and returns its parsed JSON output -- for example, run(args=["feed", "--source", "cisa-kev", "--json"]) returns the parsed FeedItem[] JSON for the CISA-KEV connector's current feed, the same data truesignal feed --source cisa-kev --json prints on the command line. Every failure mode (missing CLI, timeout, non-zero exit, unparseable output) is caught and returned as {"error": ...} instead of raising. See python/src/truesignal/mcp_server.py for the implementation.

How TrueSignal compares

Every cell below is a cited, checkable fact, current as of 2026-08-03, drawn only from tools actually run in this pass. See benchmarks/ for the reproduction command behind every TrueSignal number.

| | TrueSignal | Crucix