tibet-trail 0.1.0

CLI audit trail reader for TIBET provenance tokens

tibet-trail

CLI audit trail reader for TIBET provenance tokens. Reads, searches, and monitors JSONL files written by tibet-core FileStore.

Install

pip install tibet-trail

Commands

# Show recent tokens (default: 20)
tibet-trail log audit.jsonl [-n 50] [--format json|csv|text]

# Search by action/actor/time
tibet-trail search audit.jsonl --actor jis:hub --action "ping.*" --since 1h

# Trace provenance chain
tibet-trail trace audit.jsonl <token_id> [--depth 50]

# Live follow (tail -f style)
tibet-trail watch audit.jsonl [--filter-actor jis:hub]

# Verify integrity
tibet-trail verify audit.jsonl [--key <hex>]

# Statistics
tibet-trail stats audit.jsonl [--format json]

# Export to file
tibet-trail export audit.jsonl output.csv --format csv

Time Filters

The --since flag accepts relative times: 30s, 5m, 1h, 2d, 1w or ISO timestamps.

Python API

from tibet_trail import TrailReader

reader = TrailReader("audit.jsonl")

# Last 10 tokens
for token in reader.log(n=10):
    print(f"{token.timestamp}: {token.action} ({token.actor})")

# Search with regex
results = reader.search(action="ping.*", actor="jis:hub", since="1h")

# Trace chain
chain = reader.trace("tibet_20241217_abc12345")

# Verify integrity
report = reader.verify()
print(f"Integrity: {report['integrity']}")

# Stats
stats = reader.stats()
print(f"Total: {stats['total']}, Actors: {stats['actors']}")

Development

pip install -e ".[dev]"
pytest tests/ -v

License

MIT