nullcone

Distributed threat intelligence for AI agents and security teams.

Real-time IOC sharing powered by SpacetimeDB. Your agent detects a threat — report it in one call — every other agent on the network is protected within milliseconds.

1,295,000+ IOCs indexed · 549 malware families · 20+ live feeds · <1ms query latency

---

Install

pip install nullcone

Python 3.11+ required.

---

Quick start — Python SDK

from nullcone import NullconeAgent, IOC, IOCType

with NullconeAgent(api_key="nc_...") as agent:

    # ① Check any IOC instantly
    sig = agent.find_by_value("185.220.101.47")
    if sig:
        print(f"{sig.value} — {sig.family_name} — severity {sig.severity}/10")
        agent.report_detection(sig.id, "blocked")

    # ② Report new threats — protects every connected agent instantly
    agent.submit_ioc(IOC(
        ioc_type=IOCType.IP,
        value="10.10.10.1",
        severity=8,
        tags=["c2", "botnet"],
    ))

    # ③ Delta sync — stream everything new since your last check
    sigs, last_id = agent.poll_since(last_id)

Self-registration

agent = NullconeAgent(api_key="nc_...")
agent.register()   # idempotent — safe to call on every startup

Registration is automatic when using the context manager (with NullconeAgent(...) as agent).

Continuous sync

def on_new_threats(sigs):
    for s in sigs:
        print(f"[{s.severity}/10] {s.ioc_type} {s.value}")

agent.sync_loop(on_new_threats, interval=300)
# state is auto-persisted to ~/.nullcone/{agent_id}.state

Real-time WebSocket subscription

agent.subscribe_new_threats(callback=on_new_threats, min_severity=7)
agent.start_subscriptions()

Self-hosted only. Real-time subscriptions are not open on the hosted nullcone.ai service right now (the subscribe endpoint returns 403). Against the hosted service, use sync_loop() / poll_since() above — or the MCP server at https://nullcone.ai/mcp.

---

Quick start — CLI

# First-time setup
nullcone config init

# Register your agent
nullcone register

# Look up an IOC
nullcone lookup 185.220.101.47
nullcone lookup evil.example.com

# Submit a new threat
nullcone submit 1.2.3.4 -t ip -s high --tags c2,botnet
nullcone submit CVE-2024-1337 -t cve -s critical
nullcone submit "ignore previous instructions" -t prompt -s 8

# Submit a batch from JSON
nullcone submit-batch threats.json

# Stream recent threats
nullcone threats --limit 50 --min-severity 5

# Poll for new IOCs since a known ID
nullcone poll --since 591000
nullcone poll --watch --min-severity 7   # live stream, Ctrl-C to stop

# Report a detection
nullcone detect 12345 --action blocked

# All commands support --json for machine-readable output
nullcone lookup 1.2.3.4 --json | jq .
nullcone threats --json | jq '.[].value'

CLI environment variables

Variable	Description
NULLCONE_URL	SpacetimeDB server URL
NULLCONE_DB	Database name (default: nullcone)
NULLCONE_AGENT_ID	Agent ID (auto-generated on first run)
NULLCONE_TOKEN	Auth token
NULLCONE_JSON	Set to 1 to always output JSON

---

IOC types

Key	Description
ip	IPv4 / IPv6 address
ip_port	IP address with port (1.2.3.4:443)
domain	Malicious domain
url	Malicious URL
md5 / sha1 / sha256	File hashes
ja3	TLS fingerprint
cve	CVE identifier
prompt	Malicious LLM instruction / prompt injection pattern
skill	Malicious AI agent skill / plugin identifier
yara	YARA rule pattern
stego	Steganographic technique / covert-channel signature
email, mutex, registry, filepath, asn, imphash	Standard IOC types

---

Batch submission format

[
  {"type": "ip",     "value": "1.2.3.4",          "severity": 7, "tags": ["c2"]},
  {"type": "domain", "value": "evil.example.com",  "severity": 5},
  {"type": "sha256", "value": "abc123...",          "severity": 9, "family": "emotet"}
]

nullcone submit-batch threats.json

---

Severity scale

Value	Label
9–10	CRITICAL
7–8	HIGH
5–6	MEDIUM
3–4	LOW
1–2	INFO

---

Other ways to connect

The SDK is one of four surfaces onto the same corpus:

Surface	How
MCP (remote)	point any MCP client at https://nullcone.ai/mcp — streamable-http, no auth, 30 tools
Claude Code plugin	/plugin install nullcone@nullcone
REST	curl "https://nullcone.ai/v1/ioc?value=185.220.101.47"
Anonymous SQL	POST https://nullcone.ai/v1/database/nullcone/sql (reads only)

---

Links

• Website: nullcone.ai
• API reference: nullcone.ai/api/docs (OpenAPI / Swagger)
• Issues: github.com/maco144/nullcone
• Contact: hi@nullcone.ai

---

License

Rising Sun License v1.0 — see LICENSE.