Holocron 4.0
DarkMatter Software | K0NxT3D
Python / PySide6 ASN Intelligence Console

============================================================
WHAT CHANGED
============================================================

Holocron 4.0 replaces the Go + embedded WebView desktop client
with a native Python + PySide6 interface.

The ASN database process is now part of Holocron itself.

Core functions:
- Search local ASN database by ASN, organization, type, location
- Live announced-prefix lookup through RIPEstat
- Export ASN results to CSV
- Export live prefixes to CSV
- Inspect ASN database status
- Verify SQLite integrity
- Rebuild asn.db from current bgp.tools data
- Preserve the active database until a rebuilt database validates

============================================================
ASN DATABASE PIPELINE
============================================================

Primary ASN source:
    https://bgp.tools/asns.csv

Fields:
    asn
    name
    class

Country enrichment:
    bgp.tools WHOIS bulk interface on TCP port 43

Final schema:

    CREATE TABLE asn (
        asn TEXT PRIMARY KEY,
        name TEXT NOT NULL DEFAULT '',
        type TEXT NOT NULL DEFAULT 'Unknown',
        location TEXT NOT NULL DEFAULT ''
    );

Holocron 4.0 also adds a metadata table containing:
- schema_version
- source
- source_url
- built_at
- record_count
- builder

The rebuild engine creates a temporary database first. It runs
PRAGMA integrity_check and verifies the record count before the
new database replaces the active database.

The previous database is retained as:
    asn.db.bak

============================================================
RUN FROM SOURCE
============================================================

Ubuntu / Debian:

    sudo apt install python3-venv
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt
    python holocron.py

============================================================
BUILD
============================================================

    chmod +x build.sh
    ./build.sh

The PyInstaller executable is written to:

    dist/Holocron

============================================================
DATABASE LOCATION
============================================================

Development:
    data/asn.db

Holocron also recognizes a legacy:
    ./asn.db

For a packaged application, the recommended writable layout is:

    Holocron
    data/
        asn.db
    assets/
        css/
            default.qss

============================================================
NETWORK ACCESS
============================================================

Database rebuild:
- HTTPS to bgp.tools/asns.csv
- TCP port 43 to bgp.tools for bulk WHOIS country metadata

Live prefix lookup:
- HTTPS to stat.ripe.net

Normal ASN searches are local SQLite operations.

============================================================
END
============================================================


============================================================
HOLOCRON 4.0 ASN DATABASE SOURCE
============================================================

Holocron 4.0 rebuilds asn.db from:

    Alice39s/BGP.Tools-OpenDB

Latest snapshot branch:
    auto-update

Primary source:
    asns/asns.csv.gz

Fallback source:
    asns/asns.csv

Dataset columns:
    asn,name,class,cc

Holocron mapping:
    asn   -> asn
    name  -> name
    class -> type
    cc    -> location

This preserves the bgp.tools classification terminology used by
the original Holocron database, including:
    Eyeball
    Transit
    Content
    Unknown

The OpenDB project states that its data is sourced from bgp.tools
and that the ASN mapping snapshot is updated daily.

No PeeringDB account or API key is required by Holocron's
database rebuild process.

DATABASE SAFETY

Holocron builds a temporary database first and validates:
- expected four-column source schema
- minimum 100,000 valid ASN rows
- AS10000 exists
- AS10000 classification is Eyeball
- SQLite PRAGMA integrity_check
- final SQLite row count

Only after all checks pass is the active database replaced.
The previous database is retained as:
    asn.db.bak
