Metadata-Version: 2.4
Name: ctidb-bin
Version: 0.0.6
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")
    if rec:
        print(rec["country_code"], rec["as_name"])
        print("hosting:", rec.get("is_hosting"), "cloud:", rec.get("is_cloud"))
        print("score in/out:", rec.get("inbound_score"), rec.get("outbound_score"))
    else:
        print("not found")
```

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

## Record fields

| Field | Description |
|---|---|
| `country_code`, `as_name` | Geo / AS info |
| `outbound_score`, `inbound_score` | Outbound / inbound threat score (0–5) |
| `is_vpn`, `is_tor`, `is_cdn`, `is_proxy`, `is_hosting`, `is_cloud`, `is_c2`, `is_honeypot`, `is_mobile` | Category tags (always present, `True`/`False`) |
| `hostname`, `representative_domain`, `ssl_certificate`, `products`, `cve`, `open_ports`, `tags` | Detail fields (Full plan only) |

## Notes

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

## License

Apache-2.0 · © AI Spera
