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] <item-id>  Re-fetch the source connector named in <item-id>
                              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 <name>] [--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 <item-id> [--json]

Re-fetches the source named in <item-id> (format <source>:<native-id>, 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

Read the full README on GitHub →