Metadata-Version: 2.4
Name: tibet-bom
Version: 0.2.0
Summary: TIBET Bill Of Hack — dataset-driven operator-side attack inventory with collection, storage, and report 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 dataset-driven forensic CLI for turning attack windows into a
repeatable **Bill Of Hack**:

- what was hit
- when it was hit
- where the evidence came from
- how the substrate classified it
- which artefacts corroborate the claim

It started with the confirmed Humotica Phase 5 slice, but it now stores and
switches between multiple datasets instead of pretending one hardcoded window is
the current machine.

## What It Is

`tibet-bom` is now:

- an executable BOM renderer
- a local dataset registry
- an import/collection tool
- a report export layer

It is **not yet** a full autodiscovery agent for every host and log source. The
current architecture is adapter-driven: collect/import evidence into datasets,
then render `info`, `report`, `json`, or `markdown` against the selected one.

## Core Model

Every dataset contains:

- window metadata
- evidence host metadata
- entries
- artefact hashes
- time-source disclosure
- NIS2 context
- canonical examples

The CLI always distinguishes:

- `Runtime`: where you are running `tibet-bom`
- `Evidence host`: the host the BOM dataset actually describes

That avoids the earlier failure mode where a laptop install looked like it *was*
P520.

## 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
PYTHONPATH=src python -m tibet_bom info
```

## Storage

Datasets are stored in:

- `$TIBET_BOM_HOME` if set
- otherwise `$XDG_DATA_HOME/tibet-bom` when writable
- otherwise `~/.local/share/tibet-bom` when writable
- otherwise `./.tibet-bom`

This fallback chain matters on restricted systems where `$HOME` is not writable.

## Commands

Render commands:

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

Dataset commands:

```bash
tibet-bom datasets
tibet-bom use phase5-confirmed
tibet-bom collect fixture-phase5 --set-active
tibet-bom collect json --file ./dataset.json --set-active
tibet-bom collect bundle --path ./evidence-bundle --set-active
```

Runtime collection:

```bash
tibet-bom collect runtime \
  --name may8-lab \
  --set-active \
  --evidence-host "lab-host-01" \
  --actor "10.0.0.7" \
  --window-start "2026-05-08 12:00:00 UTC" \
  --window-end "2026-05-08 12:05:00 UTC" \
  --duration "~5 minutes" \
  --db-asc "10-17" \
  --db-desc "300-293" \
  --chain-route-status "typed views verified; public route unknown" \
  --surface-label "TIBET signing surface" \
  --surface-label "AINS lookup surface" \
  --entry-json ./entries.json \
  --artifact /var/log/nginx/access.log \
  --time-source-json ./time-source.json \
  --nis2-json ./nis2.json \
  --canonical-json ./canonical.json
```

## Evidence Bundle Convention

`collect bundle --path DIR` looks for:

- `metadata.json`
- `entries.json` or `entries.jsonl`
- optional `artifact_hashes.json`
- optional `time_source.json`
- optional `surface_labels.json`
- optional `nis2_context.json`
- optional `canonical_examples.json`

This makes it easy to package incident exports per machine and per situation.

## Built-In Dataset

The package still ships with one built-in confirmed dataset:

- dataset: `phase5-confirmed`
- evidence host: `P520 staging (10.0.100.2)`
- actor: `10.0.100.11`
- window: `2026-05-04 12:27:24 UTC` -> `2026-05-04 12:29:39 UTC`
- absolute DB positions: `407-423`

This remains useful as:

- a reference dataset
- a regression fixture
- a publishable example of a complete BOM

## Time-Source Position

TIBET-BOM does not treat NTP as the source of truth for event order.

Primary truth:

- TIBET causal / logical ordering
- happened-before relationships
- generation continuity
- chain integrity

Secondary truth:

- wall-clock alignment
- drift disclosure
- cross-host correlation

So `time-source` is an alignment layer, not the epistemic center of the tool.

## Current Scope

What is implemented now:

- dataset storage and selection
- built-in Phase 5 fixture bootstrap
- import from JSON
- import from conventional evidence bundles
- runtime dataset collection from supplied files
- artefact hashing
- report/json/markdown export

What is still next:

- direct Postgres adapters
- direct journald adapters
- direct nginx parser adapters
- typed-view to BOM auto-builders
- host profiles such as `--profile phase5`

## Status

This release turns `tibet-bom` from a single packaged demo window into a
multi-dataset **Bill Of Hack** tool with a real local registry and collection
path.
