Metadata-Version: 2.5
Name: attribution-suite
Version: 0.6.0
Summary: One install and one CLI over the attribution-graph toolchain
Project-URL: Homepage, https://github.com/OWNER/attribution-suite
Author: Tushar Karumudi
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: attribution,entity-resolution,osint,threat-intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: adtx-attribution>=0.6.0
Requires-Dist: attribution-graph>=0.6.0
Requires-Dist: handle-correlation>=0.6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# attribution-suite

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

One install and one CLI over the attribution toolchain.

```bash
pip install attribution-suite
attribution run --case case.yaml --index adtx.sqlite --out ./out
```

## Why the packages are separate at all

[`attribution-graph`](https://github.com/OWNER/attribution-graph) is a pure
inference library with no network I/O — that is what makes its scoring auditable,
since every number is a function of claims plus index counts with no hidden
network state. [`adtx-attribution`](https://github.com/OWNER/adtx-attribution)
carries the collectors and their dependencies.
[`handle-correlation`](https://github.com/OWNER/handle-correlation) is
independent of both.

Someone who only wants the scoring model should not have to install an HTTP
client, and someone writing their own collectors should not inherit ours. This
package exists for when you want all of it.

## Unified run

One case file drives the whole chain:

```bash
attribution run \
  --case case.yaml \
  --index adtx.sqlite \
  --handles observed_handles.csv \
  --spiderfoot scan.db \
  --opencti bundle.json \
  --robin investigations/kraken.json \
  --out ./out
```

Robin handles feed the handle-correlation pass automatically, carrying the
durable identifiers found alongside them. `.onion`-derived claims raise a warning
in the run summary: those sources have no archive and no preserved body, so they
cannot be verified after the fact by anyone, including you.

Order is fixed, and the ordering is the point: imported claims seed the frontier
before collection, adversarial checks run before scoring so a planted identifier
never reaches the model at full weight, and evidence verification runs before
reporting so findings from a package that failed its integrity check are never
presented. **`attribution run` exits non-zero if verification fails**, so a
scripted caller can detect an unpresentable result.

## Passthrough commands

```bash
attribution index build --domains tranco.txt --db adtx.sqlite
attribution portfolio scraper-site.example --index adtx.sqlite --registrants
attribution handles --observations handles.csv --corpus usernames.txt
attribution registries --jurisdiction IN
attribution verify ./out/evidence
attribution version
```

These delegate to the component CLIs rather than duplicating their flags.

## Outputs

| File | What it is |
|---|---|
| `attribution_report.md` / `.html` | Findings, ICD 203 language, source terms |
| `verification_trail.md` | Ordered timestamped steps with numbered citations |
| `investigation_graph.json` | Every claim with full provenance |
| `entities.ftm.json` | FollowTheMoney — loads into yente / Aleph |
| `graph.cypher` | Neo4j |
| `evidence/evidence_manifest.json` | Hash-chained capture record |
| `evidence/verify.py` | Standalone integrity checker, no dependencies |
| `evidence/DECLARATION_DRAFT.md` | Qualified-person certification skeleton |

## Collection policy

`robots_policy` in the case file: `respect`, `record` (default), or `ignore`.

There is no silent enforcement — robots.txt is routinely bypassed in practice and
a library pretending otherwise would be enforcing an abandoned norm. What matters
for this toolchain is different: the output is meant to survive review, and the
question there is never "did the tool obey robots.txt" but "can you state what
your collection policy was". Whichever setting you choose is written into the
evidence manifest and the declaration draft.

In practice it rarely bites. RDAP, crt.sh, GLEIF, EDGAR, `sellers.json` and
`ads.txt` are all published for machine consumption; only imprint scraping and
county-records HTML touch robots-relevant paths.

## Version reporting

Every run prints the version of each component, and `attribution version` reports
them. A finding that cannot name its toolchain is hard to re-examine once the
scoring model has moved.

## License

Apache-2.0.
