Metadata-Version: 2.4
Name: ctidb-bin
Version: 0.0.7
Summary: Python reader for Criminal IP packed CTI database (.bin) files
Project-URL: Homepage, https://www.criminalip.io
Author-email: AI Spera <infra@aispera.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: criminalip,ctidb,packed-binary,threat-intelligence
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pycryptodomex>=3.20
Requires-Dist: zstandard>=0.22
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: fast
Requires-Dist: pyroaring>=1.0; extra == 'fast'
Description-Content-Type: text/markdown

# ctidb-bin

Python reader for **Criminal IP** packed CTI database files (`*.bin`).

Fast, read-only IP threat-intelligence lookup from the packed Criminal IP
database distributed to licensed customers. For the legacy MMDB format, use the
[`ctidb`](https://pypi.org/project/ctidb/) package instead.

## Installation

```bash
pip install ctidb-bin
```

Requires Python 3.9+.

## Usage

```python
from ctidb_bin import PackedReader

with PackedReader.open("criminalip.ctidb.bin") as reader:
    rec = reader.get("8.8.8.8")
    print(rec)
```

`get(ip)` returns the record for the IPv4 address as a `dict`, or `None` if the
address is not in the database.

### Example output (Full plan)

```json
{
  "country_code": "US",
  "as_name": "Google LLC",
  "city": "Mountain View",
  "is_vpn": false,
  "is_tor": false,
  "is_cdn": false,
  "is_proxy": false,
  "is_hosting": true,
  "is_cloud": true,
  "is_c2": false,
  "is_honeypot": false,
  "abuse_record": false,
  "is_mobile": false,
  "score": false,
  "connected_domains": false,
  "outbound_score": 1,
  "inbound_score": 1,
  "hostname": "dns.google",
  "representative_domain": "google.com",
  "ssl_certificate": ["dns.google"],
  "products": ["HTML 5.0"],
  "cve": [],
  "open_ports": [443],
  "tags": []
}
```

## Field reference

| Field | Type | Description |
|---|---|---|
| `country_code` | `str` | ISO 3166-1 alpha-2 country code |
| `as_name` | `str` | Autonomous System (owner) name |
| `city` | `str` | City (country-level approximation) |
| `is_vpn` | `bool` | VPN endpoint |
| `is_tor` | `bool` | Tor node |
| `is_cdn` | `bool` | CDN |
| `is_proxy` | `bool` | Proxy |
| `is_hosting` | `bool` | Hosting provider |
| `is_cloud` | `bool` | Cloud provider |
| `is_c2` | `bool` | Command-and-control server |
| `is_honeypot` | `bool` | Honeypot / botnet-observed |
| `is_mobile` | `bool` | Mobile carrier network |
| `abuse_record` | `bool` | Has an abuse record |
| `connected_domains` | `bool` | Has connected domains |
| `mobile_botnet` | `bool` | Mobile botnet |
| `score` | `bool` | Critical (inbound or outbound score ≥ 5) |
| `outbound_score` | `int` | Outbound threat score (0–5) |
| `inbound_score` | `int` | Inbound threat score (0–5) |
| `hostname` | `str` | Reverse-DNS hostname |
| `representative_domain` | `str` | Representative domain |
| `ssl_certificate` | `list[str]` | SSL certificate common name(s) |
| `products` | `list[str]` | Detected products / banners |
| `cve` | `list[str]` | CVE identifiers |
| `open_ports` | `list[int]` | Open ports |
| `tags` | `list[str]` | Classification tags |

## Fields by plan

The field set depends on your CTIDB plan. A lighter plan is a strict subset of a
heavier one.

| Field group | Geolocation | TI / C2 | Fraud Detection | Full |
|---|:---:|:---:|:---:|:---:|
| `country_code`, `as_name`, `city` | ✓ | ✓ | ✓ | ✓ |
| `is_c2`, `is_honeypot`, `abuse_record`, `connected_domains`, `mobile_botnet`, `score` | | ✓ | ✓ | ✓ |
| `is_vpn`, `is_tor`, `is_cdn`, `is_proxy`, `is_hosting`, `is_cloud`, `is_mobile` | | | ✓ | ✓ |
| `outbound_score`, `inbound_score` | | | ✓ | ✓ |
| `hostname`, `representative_domain`, `ssl_certificate`, `products`, `cve`, `open_ports`, `tags` | | | | ✓ |

Notes:
- Fields are **plan-driven**: a record only contains the fields your plan provides.
- Within a plan, boolean tags are always present (`True`/`False`); list fields
  are always present (empty `[]` when the IP has no such data).
- An IP that was not observed on the build date carries only base information
  (geo + provider flags); detail fields (`open_ports`, `products`, …) are empty.

## Notes

- The database file is provided through your Criminal IP download link.
- Files are cryptographically signed; a tampered file is rejected on open.

## License

Apache-2.0 · © AI Spera
