● Notice //GitHub (@shehzade) is temporarily suspended pending an automated false-positive review. All tools are hosted on this Code Mirror and available on request (contact); GitHub links will return once reinstated.
PUBLIC MIRRORGo v1.0

Multi-protocol network egress assessment and DLP verification framework featuring automated L4 sweeps, corporate proxy traversal, and covert protocol smuggling across 20+ channels.

$ git clone https://shehzade.io/repos/contraband.git Copy
Source ZIP (1.93 MB)
Code 174 Commits 1
contraband / pkg / server / state / ledger.go
← Back to directory
88 lines · 3.0 KB
Raw
1package state
2
3import (
4 "errors"
5 "time"
6
7 "github.com/shehzade/contraband/pkg/common"
8)
9
10var (
11 ErrLedgerClosed = errors.New("ledger is closed")
12 ErrSessionNotFound = errors.New("session not found")
13 ErrProbeNotFound = errors.New("probe result not found")
14 ErrInvalidChunk = errors.New("invalid chunk sequence or length")
15 ErrHashMismatch = errors.New("payload hash does not match expected hash")
16 ErrSessionIncomplete = errors.New("session payload not fully reassembled or incomplete")
17)
18
19// LedgerObserver receives asynchronous notifications of live chunk arrivals and session completions.
20type LedgerObserver interface {
21 OnChunkReceived(session *common.Session, seq, total uint32, chunkSize int64)
22 OnSessionCompleted(session *common.Session)
23}
24
25// ProbeObserver receives live notifications of recorded probes.
26type ProbeObserver interface {
27 OnProbeRecorded(probe *common.ProbeResult)
28}
29
30// Ledger defines the thread-safe contract for storing probes, tracking sessions,
31// assembling chunks, and capturing forensic credentials across all server listeners.
32type Ledger interface {
33 // Probe Operations
34 RecordProbe(result common.ProbeResult) error
35 GetProbe(id string) (*common.ProbeResult, error)
36 GetAllProbes() ([]common.ProbeResult, error)
37
38 // Session Operations
39 GetSession(token common.SessionToken) (*common.Session, error)
40 UpdateSession(session *common.Session) error
41 GetAllSessions() ([]*common.Session, error)
42
43 // Chunk Assembly & Hash Verification
44 AssembleChunk(token common.SessionToken, seq uint32, total uint32, payload []byte, expectedHash string) (*common.Session, bool, error)
45 AssembleChunkWithMeta(token common.SessionToken, seq uint32, total uint32, payload []byte, expectedHash, clientIP, protocol string, port int, clientHost, networkZone string) (*common.Session, bool, error)
46 GetSessionPayload(token common.SessionToken) ([]byte, error)
47
48 // Credential Capture Operations
49 RecordCredential(cred common.CapturedCredential) error
50 GetCredentials() ([]common.CapturedCredential, error)
51
52 // Forensic Export & Lifecycle
53 ExportJSON() ([]byte, error)
54 Reset() error
55 Close() error
56
57 // Observer attachment
58 SetObserver(obs LedgerObserver)
59}
60
61// NewLedger creates a polymorphic Ledger instance. If dbPath is empty or ":memory:",
62// it initializes a fast in-memory ledger. Otherwise, it opens a pure-Go SQLite ledger.
63func NewLedger(dbPath string) (Ledger, error) {
64 if dbPath == "" || dbPath == ":memory:" {
65 return NewMemoryLedger(), nil
66 }
67 return NewSQLiteLedger(dbPath)
68}
69
70// CloneSession creates a deep copy of a Session struct to prevent data races.
71func CloneSession(s *common.Session) *common.Session {
72 if s == nil {
73 return nil
74 }
75 copied := *s
76 if s.Chunks != nil {
77 copied.Chunks = make(map[uint32]common.ChunkRecord, len(s.Chunks))
78 for k, v := range s.Chunks {
79 copied.Chunks[k] = v
80 }
81 }
82 return &copied
83}
84
85// FormatTimeMS returns the duration formatted in milliseconds.
86func FormatTimeMS(d time.Duration) float64 {
87 return float64(d.Microseconds()) / 1000.0
88}