Home

Welcome to the BloomRepo Documentation & Knowledge Base

BloomRepo is a security-first, high-performance repository discovery, continuous monitoring, and authorized local static analysis platform engineered in Rust.

Unlike standard crawlers that simply catalog repositories based on raw keyword matches, BloomRepo is designed around transactional durability, explainable triage, change evolution tracking, and safe, offline-capable static analysis.

BloomRepo Interface

🧭 Wiki Table of Contents & Quick Navigation

Section	Focus Area	Description
Architecture Overview	Internal Engine	How discovery, ingestion, atomic transactions, and delivery outbox operate
Core Pillars	Design Philosophy	Explainable triage, durability guarantees, and defensive boundaries
Configuration Reference	`config.toml`	Key configuration options, rate limits, and monitoring parameters
Local Static Analysis & SBOM	Security Engine	Passive scanning, CycloneDX 1.5 SBOM generation, and OSV integration
CLI & GUI Usage Cheatsheet	Operations	Quick command reference for operators and automated pipelines
Roadmap & Evolution	Development	Current milestones, stability guarantees, and planned capabilities

🏛 System Architecture

BloomRepo follows a strict separation of concerns, ensuring that network discovery, persistent storage, notification dispatch, and security evaluations never leak credentials or execute unverified third-party code.

flowchart TD
    subgraph Ingestion ["Ingestion & Discovery"]
        GH[GitHub REST / Events API] --> RL[Token Bucket & Rate Limiter]
        RL --> CRAWLER[Discovery Crawler]
    end

    subgraph Evaluation ["Evaluation & Triage"]
        CRAWLER --> FILTER[RepoFilter: Explainable Triage]
        FILTER --> SCORE[Scoring: Relevance & Confidence]
    end

    subgraph Storage ["Durable Storage Engine"]
        SCORE --> TX[Atomic Transaction]
        TX --> DB[(SQLite + WAL + FTS5)]
        TX --> OUTBOX[Transactional Outbox Queue]
    end

    subgraph Dispatch ["Durable Delivery"]
        OUTBOX --> NOTIFIER[Notification Dispatcher]
        NOTIFIER --> WH[Secure Webhooks]
        NOTIFIER --> TG[Telegram Bot]
        NOTIFIER --> TOAST[Windows Toast Notifications]
    end

    subgraph Analysis ["Local Static Analysis (Authorized Only)"]
        LOCAL[Local Directory] --> BOUND[Filesystem Jail & Safe Traversal]
        BOUND --> AST[Passive AST / Manifest Parsers]
        AST --> SBOM[CycloneDX 1.5 JSON SBOM]
        AST --> OSV[OSV Vulnerability Correlation]
    end

🛡 Core Architectural Pillars

1. Reliability & Transactional Outbox

Atomic State Persistence: Repositories, crawl cursors, and pending notification events are persisted within a single ACID transaction in SQLite (WAL mode).
Guaranteed Delivery: If network loss or a process interruption occurs, notifications remain safely queued in the Transactional Outbox and are retried with exponential backoff and jitter upon recovery.

2. Explainable Triage (No Blind Scoring)

Separation of Concerns: Interest relevance and evidence confidence are scored independently. BloomRepo never flags a repository as "malicious" purely because it contains terms like exploit or cve in its description.
Transparent Decisions: Every repository decision records why it was accepted, deferred, or filtered, noting missing metadata fields (such as missing license or unverified primary language).

3. Continuous Evolution & Watchlist Tracking

Drift Detection: Tracks releases, dependency tree changes, license modifications, and project archival status across watched repositories.
Actionable Intelligence: Alerts focus on what changed and why it matters, rather than noisy flood alerts for unchanged projects.

4. Safe, Passive Local Static Analysis

Strictly Non-Executable: Never compiles, executes, or runs arbitrary third-party scripts. Traversal is strictly passive.
Jail & Symlink Protections: Rejects symlink traversal, directory traversal attempts (..), junction points, and non-UTF-8 anomalies.
Standards-Compliant SBOM: Produces standards-compliant CycloneDX 1.5 JSON software bill of materials and maps packages to known OSV (Open Source Vulnerabilities) advisories.
Automated Secret Redaction: API keys, access tokens, and credentials identified during scanning are fully redacted before reporting or export.

⚙ Configuration Quick Reference

BloomRepo is configured via a declarative config.toml. A minimal baseline includes:

[storage]
database_path = "bloomrepo.db"
enable_wal = true

[filtering]
enable_spam_filter = true
priority_keywords = ["rust", "security", "agent"]
min_description_length = 15

[monitoring]
check_interval_seconds = 300
batch_size = 50

[notifications]
enable_windows_toast = true
toast_priority_only = true
# webhook_url = "https://your-domain.com/webhook"

Tip

Always validate your configuration before running unattended daemons:

bloomrepo --config config.toml --validate-config

💻 Command-Line & GUI Cheatsheet

Terminal Commands

Launch the Interactive GUI:
```
bloomrepo
```
One-Shot Crawl & Ingestion:
```
bloomrepo --once
```

Offline Search across Ingested Repositories:

bloomrepo --search "query terms" --format table

Perform Authorized Local Static Analysis:

bloomrepo --analyze-path "C:\path\to\authorized\repo" --export-sbom sbom.json

Validate Configuration File:

bloomrepo --config config.toml --validate-config

🗺 Project Roadmap

v1.x - Foundation: SQLite FTS5 search, basic GitHub Search API crawler, immediate alerts.
v2.x - GUI & Multichannel Delivery: egui native UI, Webhook and Telegram dispatchers, multi-token rotation.
v3.0 - Enterprise Intelligence & Defense: Transactional Outbox, explainable confidence scoring, CycloneDX 1.5 SBOM, OSV advisory correlation, strict Windows handle-relative filesystem traversal.
v3.1 - Enhanced Watchlist Analytics: Automated diffing across release tag changelogs and deeper license compliance audit checks.

🤝 Contributing & Security Disclosures

Source Code: okba14/BloomRepo
Issue Tracker: Report bugs or request features via GitHub Issues.
Security Reports: Please report sensitive vulnerabilities directly according to our security policy.

Navigation Menu

Repository navigation