Metadata-Version: 2.4
Name: tibet-bom
Version: 0.1.2
Summary: TIBET Bill Of Hack — operator-side attack inventory with chain positions, corroborating artefacts, and markdown export
Project-URL: Homepage, https://humotica.com
Project-URL: Documentation, https://humotica.com/docs/tibet-bom
Project-URL: TIBET Protocol, https://pypi.org/project/tibet-core/
Author-email: Codex <ai@humotica.nl>
Maintainer-email: Humotica AI Lab <ai@humotica.nl>
License: MIT
Keywords: bill-of-hack,bom,forensics,pentest,phase5,provenance,redspecter,tibet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# tibet-bom — TIBET Bill Of Hack

**Every adversarial action indexed. Every operator-side artefact anchored.**

`tibet-bom` is a compact operator-side evidence unit for pentest and
incident-review work. It turns a noisy attack window into a chain-indexed
inventory:

- what was hit
- when it was hit
- where it happened
- how the substrate classified it
- which corroborating artefacts anchor the claim

This draft package is seeded with the confirmed Humotica Phase 5
engagement window from `2026-05-04 12:27:24 UTC` to
`2026-05-04 12:29:39 UTC`.

It should be read as the product-neighbour of `tibet-nis2`:

- `tibet-nis2` -> compliance coverage
- `tibet-bom` -> incident transparency
- next logical layer -> `tibet-incident` / `tibet-forensics`

## Why This Exists

Security reports usually describe findings. Raw logs usually describe
events. A **TIBET-BOM** sits between them:

- more compact than a full chain dump
- more auditable than prose
- more substrate-native than a classic incident summary

For the Red Specter joint paper, that makes it a good counterpart to
attacker-side evidence files.

Longer-term, this is also a credible NIS2 / ENISA / CSIRT reporting
primitive: a human-readable forensic bundle with cryptographic anchors.

## What It Covers

| Layer | Purpose | In This Unit |
|---|---|---|
| Chain positions | Where the event lives in the typed chain view | Yes |
| Timestamps | Exact UTC timing of the attack flow | Yes |
| Endpoint surface | Which substrate route was touched | Yes |
| Corroborating artefacts | nginx hashes and adjacent request evidence | Yes |
| Absolute DB positions | Verified ranks in `jtel_security.tibet_tokens` | Yes |
| Public global chain integers | Final public chain lookup mapping | Unverified |
| pcap paths/hashes | Packet capture persistence | Not yet |

## Installation

From this sandbox directory:

```bash
cd /srv/jtel-stack/sandbox/ai/codex/tibet-bom-unit
pip install -e .
```

Or run the module directly:

```bash
python -m tibet_bom info
```

## CLI Usage

```bash
tibet-bom info
tibet-bom table
tibet-bom timeline
tibet-bom report
tibet-bom artifacts
tibet-bom time-source
tibet-bom json
tibet-bom markdown
```

All commands support `--json` only where explicitly noted.
## Commands

- `info` — overview of scope, exclusion note, evidence counts, and time-source summary
- `table` — compact BOM table in terminal format
- `timeline` — ordered timeline grouped for incident review
- `report` — push-button incident transparency report (includes time-source disclosure)
- `artifacts` — corroborating artefact hashes
- `time-source` — full time-source status: evidence-server NTP sync, drift vs anchor, advisory, remediation path
- `json` — full machine-readable payload (includes `time_source_status` field)
- `markdown` — render a paper-ready markdown BOM (includes Time-Source Status section)

## Time-Source Disclosure

Forensic timestamps depend on the clock that produced them. The current
fixture reports timestamps as observed on the evidence server (P520),
whose clock state at measurement-time was:

- NTP service: **not active**
- Drift vs NTP-anchored anchor server: **+14.187s** (P520 ahead of truth)
- RTC drift: **~35s**

But the more important point is structural: TIBET already preserves
causal/logical order independently of wall-clock authority. In practice:

- `prev_token_id` preserves happened-before order
- `generation` acts as a logical counter
- `parent_token_id` captures causal predecessor relationships
- the hash chain makes the ordering tamper-evident

So the `time-source` command should be read as an **absolute-time disclosure
layer**, not as the basis of truth for event ordering. Within-window
relative ordering, sequencing, and duration remain valid from the
single-clock evidence lane plus the TIBET chain structure; cross-source
absolute comparison should account for the drift band.

## Important Exclusion

The `2026-05-05 08:38:06 UTC` `192.168.4.76` sample is **not** Phase 5
attack data. It is post-engagement house-keeping / reachability testing
and should not be cited as attacker evidence.

## DB Backsolve Status

The confirmed Phase 5 slice has been backsolved directly from
Postgres:

- absolute ascending positions in `jtel_security.tibet_tokens`:
  `407-423`
- descending ranks for the same rows:
  `298-282`

Current route caveat:

- the deployed code clearly exposes auth-gated `/api/tibet/chains`
- a live public `/api/tibet/chain/[pos]` implementation is referenced
  in paper drafts but could not be verified in the current codebase

## Status

This unit currently encodes the confirmed operator-side Phase 5 slice.
It is intended to be compared and merged with Jasper / Claude wording
once a concrete local BOM draft path exists.

## Machine-Readable Fixture

The direct DB backsolve is also stored as a reusable fixture in:

`src/tibet_bom/fixtures.py`

That fixture includes:

- exact token IDs
- timestamps
- endpoint/path fields
- absolute DB positions (`407-422` ascending)
- typed-view windows
- route-status caveat for `api/tibet/chain/[pos]`
