Guide: Using Sentinel for Audit Logs

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• IMPLEMENTATION_PLAN.md
• crates/sentinel/Cargo.toml
• Cargo.toml
• crates/sentinel/src/lib.rs
• CODE_OF_CONDUCT.md
• rustfmt.toml

Cyberpath Sentinel is a document-based DBMS written in Rust, designed with a primary focus on trust, transparency, and compliance. Its core principle, "Filesystem is the Database," makes it uniquely suited for managing audit logs. Every piece of data is stored as a file on disk, where tables are represented by folders. This design ensures that every entry is inspectable, auditable, and versionable by default.

Sentinel is explicitly identified as being "perfect for audit logs" because every entry is a distinct file that can be versioned with Git. This provides a transparent history of who changed what, when, and why. The system is engineered to produce immutable audit logs with append-only patterns, cryptographic hashing for integrity, and support for regulatory compliance standards like SOC 2, ISO 27001, and HIPAA.

Sources: README.md:10-12, README.md:16-17, README.md:30, README.md:100-102, README.md:119, IMPLEMENTATION_PLAN.md:13-15

Core Concepts for Auditing

Sentinel's design is built on several principles that are highly beneficial for creating robust audit trails.

Sources: README.md:100-104

Filesystem as the Database

The fundamental concept is that the filesystem itself acts as the database. An audit log is a "collection," which is simply a directory on the filesystem. Each individual audit event is a "document," which is a JSON file within that directory. The primary key for each audit event is its filename.

This approach allows standard UNIX tools like grep, cat, and rsync to be used for querying, inspection, and replication of audit data.

The diagram below illustrates the data storage model for an audit_logs collection.

This diagram shows a typical collection folder containing document files, a directory for soft-deleted items, a Write-Ahead Log, and an index directory.

Sources: README.md:10, README.md:33-35, README.md:94-102, IMPLEMENTATION_PLAN.md:41-57

Immutability and Soft Deletes

Sentinel is designed for "immutability by default." For audit logs, this is achieved through append-only patterns. Updates do not overwrite data; instead, they can be handled by creating new versions. Deletions are "soft," meaning a deleted document is moved to a .deleted/ sub-directory rather than being permanently erased from the filesystem. This preserves a complete, recoverable history, which is critical for auditability and compliance.

Sources: README.md:91, README.md:101, README.md:121, IMPLEMENTATION_PLAN.md:180-182

Architecture for Auditability

The architecture of Sentinel includes several components designed to ensure the integrity, durability, and security of data, which are essential for audit logs.

Key Architectural Components

The system is composed of several layers, from the client-facing API down to the filesystem. For auditing, the most relevant components are the Transaction Manager, the File I/O layer, and the Encryption & Signing module.

This flow shows how a client request passes through layers for transaction management, I/O, and security before being written to the filesystem.

Sources: README.md:105-114, IMPLEMENTATION_PLAN.md:22-34

AuditTrail Component

The implementation plan specifies a dedicated AuditTrail component for managing and reporting on audit events. This component is designed to log events, retrieve them based on filters, and generate compliance reports.

The following class diagram outlines the planned structure for audit-related data.

This diagram shows the relationship between the AuditTrail manager, the AuditEvent data structure, and related enumerations for operations and compliance standards.

Sources: IMPLEMENTATION_PLAN.md:245-276

Implementing an Audit Log Collection

To use Sentinel for audit logging, you would create a dedicated collection, such as audit_logs. Each action in your application that needs to be audited would result in a new document being inserted into this collection.

Example Structure and Usage

1. Initialize Store: Create a Store instance pointing to your data directory.
2. Create Collection: Create a collection named audit_logs. This creates a data/audit_logs/ folder.
3. Insert Audit Events: For each event, insert a new JSON document into the collection. The filename serves as the unique ID for the event.

// Example from README.md, adapted for audit logs
use cyberpath_sentinel::Store;

// Create a store
let store = Store::new("./data").expect("Failed to create store");

// Create an audit log collection
let audit_logs = store.collection("audit_logs").expect("Failed to create collection");

// Insert an audit event document
audit_logs.insert("login-attempt-2026-01-11T12:00:00Z-user123", json!({
    "timestamp": "2026-01-11T12:00:00Z",
    "user_id": "user-123",
    "source_ip": "192.168.1.100",
    "operation": "UserLogin",
    "status": "Success",
    "details": {
        "message": "User 'Alice' logged in successfully."
    }
})).expect("Failed to insert event");

Sources: README.md:71-82

Audit Event Logging Flow

The sequence diagram below illustrates the process of an application logging an audit event using the planned Sentinel components.

This diagram shows the steps from an application request to the final write on the filesystem, including interaction with the Write-Ahead Log for durability.

Sources: IMPLEMENTATION_PLAN.md:124-131, IMPLEMENTATION_PLAN.md:245-258

Audit Event Document Structure

The implementation plan outlines a detailed structure for documents, including metadata fields that are crucial for auditing.

Field	Type	Description	Source
_id	String	The document's primary key (filename).	IMPLEMENTATION_PLAN.md:61
_ts	String	ISO 8601 timestamp of the last update.	IMPLEMENTATION_PLAN.md:62
_v	Integer	The version number of the document.	IMPLEMENTATION_PLAN.md:63
_hash	String	A SHA-256 hash of the document content for integrity verification.	IMPLEMENTATION_PLAN.md:64
_sig	String	An optional RSA-2048 signature for tamper detection.	IMPLEMENTATION_PLAN.md:65
(custom)	JSON	User-defined fields for the audit event itself.	IMPLEMENTATION_PLAN.md:66-69

Sources: IMPLEMENTATION_PLAN.md:60-70

Security and Compliance Features

Sentinel's design incorporates features specifically aimed at security and regulatory compliance, making it a strong choice for sensitive audit logs.

Security Feature Summary

Feature	Description	Benefit for Audit Logs	Source
Filesystem Permissions	Uses OS-level ACLs for access control.	Granular control over who can read/write audit logs.	README.md:117
Encryption at Rest	Optional AES-256 or ChaCha20-Poly1305 encryption for files.	Protects sensitive data within audit logs from unauthorized access.	README.md:118, IMPLEMENTATION_PLAN.md:185-189
Checksums & Integrity	SHA-256 hashing to detect corruption or unintentional changes.	Ensures audit log records have not been altered.	README.md:119, IMPLEMENTATION_PLAN.md:333-336
Digital Signatures	Planned RSA-2048 signing of documents.	Provides non-repudiation and strong tamper detection.	IMPLEMENTATION_PLAN.md:338-341
Immutable Logs	Achieved via append-only patterns and soft deletes.	Guarantees a complete and unalterable history of events.	README.md:120, IMPLEMENTATION_PLAN.md:349-352

Data Integrity Verification Flow

The use of checksums and digital signatures enables a clear process for verifying the integrity of an audit log entry upon read.

This flowchart shows how Sentinel verifies the integrity of a document by checking its hash and signature before returning it.

Sources: README.md:119, IMPLEMENTATION_PLAN.md:333-341

Advanced Auditing Capabilities (Roadmap)

The project's implementation plan details several advanced features that will further enhance Sentinel's capabilities as an audit log solution.

• Git-Based Replication: This feature (Phase 5) allows the entire data store to be a Git repository. Every change (e.g., a new audit event) can be an automatic commit. This provides a distributed, fully versioned, and cryptographically secure history of the entire audit trail.
• Merkle Tree Verification: Planned for Phase 7, this feature will use Merkle trees to verify the integrity of an entire collection. This allows for efficient proof that the set of all audit logs has not been tampered with.
• Automated Compliance Reporting: The AuditTrail component (Phase 6) is designed to generate reports for standards like GDPR, SOC 2, and HIPAA by scanning the audit logs for relevant events and data points.

Sources: IMPLEMENTATION_PLAN.md:221-230, IMPLEMENTATION_PLAN.md:256-258, IMPLEMENTATION_PLAN.md:380-382

Conclusion

Cyberpath Sentinel is architected from the ground up for use cases where auditability and transparency are paramount. By leveraging the filesystem directly and incorporating principles of immutability, cryptographic verification, and operational simplicity, it provides a powerful and trustworthy solution for managing audit logs. Its roadmap indicates a continued focus on strengthening these capabilities with features like Git-based replication and automated compliance reporting, positioning it as a gold standard for transparent data storage.

Sources: README.md:16-17, README.md:152-153