Metadata-Version: 2.4
Name: nullcone
Version: 0.1.0
Summary: Distributed threat intelligence for AI agents — real-time IOC sharing via SpacetimeDB
Project-URL: Homepage, https://nullcone.ai
Project-URL: Repository, https://github.com/maco144/nullcone
Project-URL: Issues, https://github.com/maco144/nullcone/issues
Project-URL: Documentation, https://nullcone.ai/docs
Author-email: Nullcone <hello@nullcone.ai>
License: MIT
License-File: LICENSE
Keywords: ai-agents,ioc,malware,security,spacetimedb,threat-intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: websockets>=11.0
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.0; extra == 'embeddings'
Description-Content-Type: text/markdown

# nullcone

**Distributed threat intelligence for AI agents and security teams.**

Real-time IOC sharing powered by [SpacetimeDB](https://spacetimedb.com). Your agent detects a threat — report it in one call — every other agent on the network is protected within milliseconds.

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

---

## Install

```bash
pip install nullcone
```

Python 3.11+ required.

---

## Quick start — Python SDK

```python
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

```python
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

```python
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

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

---

## Quick start — CLI

```bash
# 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 |
| `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 |
| `email`, `mutex`, `registry`, `filepath`, `asn`, `imphash` | Standard IOC types |

---

## Batch submission format

```json
[
  {"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"}
]
```

```bash
nullcone submit-batch threats.json
```

---

## Severity scale

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

---

## Links

- **Website**: [nullcone.ai](https://nullcone.ai)
- **Documentation**: [nullcone.ai/docs](https://nullcone.ai/docs)
- **Issues**: [github.com/maco144/nullcone](https://github.com/maco144/nullcone/issues)
- **Contact**: [hello@nullcone.ai](mailto:hello@nullcone.ai)

---

## License

MIT — see [LICENSE](https://github.com/maco144/nullcone/blob/main/LICENSE).
