Metadata-Version: 2.4
Name: tibet-bom
Version: 0.4.1
Summary: TIBET Bill Of Hack — dataset-driven operator-side attack inventory with local and SSH collectors, 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
tibet-bom collect nginx --name edge --log /var/log/nginx/access.log --set-active
tibet-bom collect journald --name mux --unit staging-brain-api.service --since "2026-05-04 12:00:00"
tibet-bom collect postgres --name phase5-db --dbname jtel_security --query-file ./phase5.sql
tibet-bom collect ssh-journald --name remote-mux --ssh-host p520 --unit staging-brain-api.service
tibet-bom collect ssh-nginx --name remote-nginx --ssh-host p520 --log /var/log/nginx/access.log
tibet-bom collect ssh-postgres --name remote-db --ssh-host p520 --dbname jtel_security --query-file ./phase5.sql
```

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

Native collectors:

```bash
tibet-bom collect nginx \
  --name p520-nginx \
  --log /var/log/nginx/redbaron-nightfall.log.1 \
  --log /var/log/nginx/redbaron-nightfall.log.2.gz \
  --path-contains /api/ \
  --status-min 400 \
  --evidence-host "P520 staging (10.0.100.2)" \
  --set-active

tibet-bom collect journald \
  --name p520-mux \
  --unit staging-brain-api.service \
  --since "2026-05-04 12:00:00" \
  --until "2026-05-04 13:00:00" \
  --grep MUX \
  --evidence-host "P520 staging (10.0.100.2)"

tibet-bom collect postgres \
  --name p520-db \
  --dbname jtel_security \
  --query-file ./phase5.sql \
  --evidence-host "P520 staging (10.0.100.2)"
```

Remote collectors:

```bash
tibet-bom collect ssh-journald \
  --name p520-mux-remote \
  --ssh-host 10.0.100.2 \
  --ssh-user root \
  --unit staging-brain-api.service \
  --since "2026-05-04 12:00:00" \
  --grep MUX \
  --evidence-host "P520 staging (10.0.100.2)"

tibet-bom collect ssh-nginx \
  --name p520-nginx-remote \
  --ssh-host 10.0.100.2 \
  --ssh-user root \
  --log /var/log/nginx/redbaron-nightfall.log.1 \
  --log /var/log/nginx/redbaron-nightfall.log.2.gz \
  --path-contains /api/ \
  --status-min 400

tibet-bom collect ssh-postgres \
  --name p520-db-remote \
  --ssh-host 10.0.100.2 \
  --ssh-user root \
  --dbname jtel_security \
  --query-file ./phase5.sql
```

## 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
- native nginx access-log collector
- native journald collector
- native Postgres/`psql` CSV collector
- explicit SSH transport collectors for nginx, journald, and Postgres
- artefact hashing
- report/json/markdown export

What is still next:

- typed-view to BOM auto-builders
- host profiles such as `--profile phase5`
- optional collector plugin API for third-party ingest adapters

## Collector Notes

- `collect nginx` parses classic nginx access-log lines, including `.gz` rotations.
- `collect journald` shells out to `journalctl -o json`; permissions therefore depend on host policy.
- `collect postgres` shells out to `psql --csv`; your query should return BOM-like columns such as `created_at`, `token_type`, `pos_asc`, `path`, `client_ip`, `erin`, or explicit `bom_id` / `view` / `position`.
- `collect ssh-*` makes the transport explicit. That keeps “local evidence” and “remote evidence over SSH” separate instead of pretending every source is local.
- These collectors are intentionally pragmatic. They turn operator evidence into a BOM dataset quickly; they are not yet a full schema-negotiated plugin framework.

## 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.
