Architecture

This document describes the architectural patterns and data flows shared across all Ilexum forensic tools.

Shared Design Principles

All three tools follow consistent architectural patterns:

Dependency Injection: Components receive their dependencies through constructors
Interface Abstraction: Platform-specific implementations behind clean interfaces
Command Logging: All OS operations logged to custody chain
RFC 5424 Compliance: Structured logging in syslog format

Component Architecture

Common Layers

Architecture CLI Flow

Custody Chain Model

The custody chain is the backbone of evidence integrity:

type CustodyChainEntry struct {
    ID               string           // UUID v4
    AgentType        string           // "bitex", "tracium", "evidex"
    AgentVersion     string
    AgentHostname    string
    AgentUser        string
    StartTimestamp   time.Time
    EndTimestamp     time.Time
    Duration         string
    MD5Hash          string
    SHA1Hash          string
    SHA256Hash        string
    TotalSizeBytes   int64
    ItemCount        int
    LogEntries       []LogEntry       // Command execution log
    CommandHistory   []CommandExecution
}

Evidence Integrity

The custody chain calculates MD5, SHA1, and SHA256 hashes over all collected evidence. Any tampering with the evidence would result in hash mismatches detectable during verification.

Data Flow

Evidence Collection Flow

Architecture CLI Flow

Bitex Data Flow

Tracium Data Flow

Evidex Data Flow

HTTP Transmission

All tools use the same transmission pattern:

type Sender struct {
    serverURL string
    authToken string
    httpClient *http.Client
}

func (s *Sender) SendEvidencePackage(pkg *EvidencePackage) error {
    jsonData, err := json.Marshal(pkg)
    if err != nil {
        return err
    }

    req, err := http.NewRequest("POST", s.serverURL, bytes.NewBuffer(jsonData))
    if err != nil {
        return err
    }

    req.Header.Set("Authorization", "Bearer "+s.authToken)
    req.Header.Set("Content-Type", "application/json")

    resp, err := s.httpClient.Do(req)
    // ...
}

Security

Always use HTTPS in production environments. The Bearer token is transmitted in plain text over HTTP.

Platform Abstraction

Tools use Go build tags for platform-specific implementations:

internal/os/
├── os.go           # Interface definition
├── default.go      # Default implementation
├── windows.go      # Windows-specific (GOOS=windows)
├── linux.go        # Linux-specific (GOOS=linux)
├── darwin.go       # macOS-specific (GOOS=darwin)
└── bsd.go          # BSD-specific (GOOS=freebsd, openbsd)