Britannic Security Sentinel (BSS)

Sovereign, offline-first, cryptographically-verified file integrity monitoring for UK Critical National Infrastructure (CNI), defence, and public sector organisations.

BSS provides a mathematically-verifiable, dependency-free alternative to American kernel-level security solutions. It is a deterministic, offline-first file integrity monitoring system that hashes monitored files into a signed manifest and periodically verifies that nothing has changed.

Version:   1.0.0
License:   Apache 2.0 (open-source core)
Language:  C11 (ISO/IEC 9899:2011)
Platform:  Linux (kernel 4.15+, glibc 2.27+ or musl)
Arch:      x86_64, ARM64 (aarch64)

---

Philosophy

The design is governed by non-negotiable principles:

1. Zero external dependencies. Only libc/libm. No third-party libraries are linked. All cryptographic primitives come from vendored, well-audited reference implementations (SHA-256/SHA-512 from scratch per FIPS 180-4; Ed25519 from the public-domain ref10 implementation per RFC 8032).
2. Offline-first. No network calls, no telemetry, no cloud communication, ever.
3. Minimal attack surface. No dynamic allocation after initialisation, bounds-checked buffers throughout, and no unsafe string functions.
4. Cryptographic purity. SHA-256, SHA-512, and Ed25519 only. No deprecated algorithms.
5. Deterministic behaviour. Same input always yields the same output.
6. Fail-secure. On any error, ambiguity, or integrity violation the system halts and alerts rather than proceeding.

---

Features

• Baseline generation — recursively scan monitored paths and hash every file.
• Manifest signing & verification — Ed25519 signatures authenticate an official manifest; tampering with either files or the manifest is detected.
• File integrity verification — every file is re-hashed and compared against the signed manifest; mismatches and missing files are reported as violations.
• Exclusion patterns — skip volatile or irrelevant paths such as /proc, /sys, /tmp.
• Fail-secure exit codes — 0 = clean, 1 = error, 2 = integrity violation (used by systemd and automation).
• Configurable hashing — SHA-256 (default) or SHA-512 per managed host.
• Hardened build — PIE, RELRO, stack protector, fortified source, strict warnings, no-exec-stack.
• Offline logging — ISO 8601 UTC, append-only log file.
• systemd integration — a oneshot service runs verification at boot and on demand.

---

System Requirements

• Linux kernel 4.15+ (x86_64 or aarch64)
• glibc 2.27+ or musl
• GCC or Clang (for building)
• ~10 MB RSS, < 500 KB stripped binary

---

Installation

From source

git clone <repo> bss && cd bss

# Build release binary and tools
make all
make tools

# Optional: run the test suite
make test

# Install to /usr/local
sudo ./scripts/install.sh

The produced binary is build/bss; the key-generation tool is build/bss-keygen.

Verify the build

make clean && make test

Expected output ends with 35 tests run, 0 failures.

---

Quick Start

# 1. Configure (see Configuration below)
sudo cp config/bss.toml.example /etc/bss/bss.toml
# edit /etc/bss/bss.toml to set your monitored paths

# 2. Generate keys (on an air-gapped host)
./scripts/generate_keys.sh keys

# 3. Distribute public.key to this host
sudo install -m 0644 keys/public.key /etc/bss/keys/public.key

# 4. Generate the baseline manifest (unsigned)
sudo bss baseline -c /etc/bss/bss.toml

# 5. Sign the manifest (on the air-gapped host)
./scripts/sign_manifest.sh /etc/bss/manifest.signed keys/private.key

# 6. Install the signed manifest and verify
sudo install -m 0600 /etc/bss/manifest.signed.signed /etc/bss/manifest.signed
bss verify -c /etc/bss/bss.toml
# => "Verification PASSED: N files checked"

---

Command Reference

bss [COMMAND] [OPTIONS]

Commands

Command	Description
baseline	Generate an unsigned baseline manifest from scanner.
verify	Verify system integrity against a signed manifest.
rebaseline	Regenerate the manifest after an authorised update.
sign	Sign a manifest with an Ed25519 private key.
help	Show help.

Options

Option	Description
-c, --config PATH	Config file path (default /etc/bss/bss.toml).
-m, --manifest PATH	Manifest file path.
-k, --key PATH	Key file path (sign).
-v, --verbose	Enable verbose output.
-q, --quiet	Suppress non-error output.
-h, --help	Show help.
-V, --version	Show version.

Exit Codes

Code	Meaning
0	Success (or clean verify)
1	General error
2	Integrity violation
64	Usage error

---

Configuration Reference

See config/bss.toml.example. A minimal TOML subset is parsed; only the documented keys are recognised.

[paths]
monitored = ["/bin", "/etc", "/usr/lib"]   # required, >= 1
excluded = ["/proc", "/sys", "/tmp"]

[behaviour]
halt_on_violation = true
verbose_logging = false

[logging]
log_file = "/var/log/bss/integrity.log"

[crypto]
hash_algorithm = "sha256"   # or "sha512"

[files]
manifest_path = "/etc/bss/manifest.signed"
public_key_path = "/etc/bss/keys/public.key"

---

Security Model

• Files are protected by their hash; the set of hashes is protected by an Ed25519 signature keyed by an offline-held private key.
• Verification is performed on the target host using only the public key.
• Any mismatch (content changed, file missing, manifest tampered) is reported as a violation and, when halt_on_violation = true, the process exits with status 2 so that boot-time automation can halt the host.
• The manifest and logging never write to the network.

See docs/SECURITY.md and docs/ARCHITECTURE.md.

---

Documentation

• ARCHITECTURE.md — component architecture and threat model
• CRYPTOGRAPHY.md — cryptographic design and standards
• BINARY_FORMAT.md — manifest binary format specification
• DEPLOYMENT.md — deployment and operations guide
• KEY_MANAGEMENT.md — key lifecycle procedures
• SECURITY.md — security & vulnerability reporting
• API.md — public module API reference

---

Performance Targets

Metric	Target
Boot-time impact (10k files SSD)	< 2 s
Boot-time impact (10k files HDD)	< 10 s
Memory footprint (RSS)	< 10 MB
CPU during verification	< 5% average
Stripped binary size	< 500 KB

---

License

This project is licensed under the Apache License, Version 2.0. See LICENSE.

The Ed25519 implementation in src/core/ed25519/ is the public-domain ref10 reference implementation (originally by Daniel J. Bernstein et al., adapted by Orson Peters), released into the public domain / CC0. See the header of those files and docs/CRYPTOGRAPHY.md for provenance.

Contributing

See CONTRIBUTING.md.

Reporting Vulnerabilities

See SECURITY.md at the repository root.