Documentation
¶
Overview ¶
NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors Package integrity provides a tamper-evident persistent audit chain
NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors Package integrity provides a Merkle hash tree for audit log integrity
Index ¶
- Variables
- func VerifyFromHash(leafHash Hash, proof []ProofStep, root Hash) bool
- type AuditChain
- func (ac *AuditChain) Append(_ context.Context, event *AuditEvent) error
- func (ac *AuditChain) Close() error
- func (ac *AuditChain) GetEvent(index int) (*ChainEntry, error)
- func (ac *AuditChain) RootHash() Hash
- func (ac *AuditChain) Size() int
- func (ac *AuditChain) Verify(_ context.Context) error
- func (ac *AuditChain) VerifyRange(_ context.Context, from, to int) error
- type AuditChainConfig
- type AuditEvent
- type ChainEntry
- type Hash
- type MerkleTree
- type ProofStep
Constants ¶
This section is empty.
Variables ¶
Functions ¶
Types ¶
type AuditChain ¶
type AuditChain struct {
// contains filtered or unexported fields
}
AuditChain is a tamper-evident, append-only log of security audit events. Each event is hashed and chained to the previous entry (prev_hash), and a Merkle tree is maintained over the entire log so that the root hash summarises all events up to that point.
Persistence is in JSONL format under the configured StoragePath directory. When the current file exceeds MaxFileSize a new segment is created.
All public methods are thread-safe.
func NewAuditChain ¶
func NewAuditChain(cfg AuditChainConfig) (*AuditChain, error)
NewAuditChain opens or creates an audit chain at the configured path. If the directory exists and contains prior segment files they are loaded and (optionally) verified.
func (*AuditChain) Append ¶
func (ac *AuditChain) Append(_ context.Context, event *AuditEvent) error
Append adds a new event to the chain. The event is hashed, linked to the previous entry, and appended to the Merkle tree before being persisted to disk.
func (*AuditChain) Close ¶
func (ac *AuditChain) Close() error
Close flushes pending writes and releases file handles.
func (*AuditChain) GetEvent ¶
func (ac *AuditChain) GetEvent(index int) (*ChainEntry, error)
GetEvent retrieves a chain entry by its index.
func (*AuditChain) RootHash ¶
func (ac *AuditChain) RootHash() Hash
RootHash returns the current Merkle root hash as a hex string.
func (*AuditChain) Size ¶
func (ac *AuditChain) Size() int
Size returns the total number of entries in the chain.
func (*AuditChain) Verify ¶
func (ac *AuditChain) Verify(_ context.Context) error
Verify checks the integrity of the entire chain from the first entry to the last.
func (*AuditChain) VerifyRange ¶
func (ac *AuditChain) VerifyRange(_ context.Context, from, to int) error
VerifyRange checks the integrity of the chain from index `from` to `to` inclusive.
type AuditChainConfig ¶
type AuditChainConfig struct {
Enabled bool // Enable the audit chain
StoragePath string // Directory for JSONL files
MaxFileSize int64 // Rotate after this many bytes (default 50 MB)
VerifyOnLoad bool // Verify full chain integrity on startup
}
AuditChainConfig configures the audit chain.
func DefaultAuditChainConfig ¶
func DefaultAuditChainConfig() AuditChainConfig
DefaultAuditChainConfig returns a reasonable default configuration.
type AuditEvent ¶
type AuditEvent struct {
Timestamp time.Time `json:"timestamp"`
Operation string `json:"operation"`
ToolName string `json:"tool_name"`
User string `json:"user"`
Source string `json:"source"`
Target string `json:"target"`
Decision string `json:"decision"` // "allowed" or "denied"
Reason string `json:"reason"`
Metadata map[string]interface{} `json:"metadata,omitempty"`
}
AuditEvent describes a single security audit event.
type ChainEntry ¶
type ChainEntry struct {
Index int `json:"index"`
Hash Hash `json:"hash"`
PrevHash Hash `json:"prev_hash"`
Event AuditEvent `json:"event"`
MerkleRoot Hash `json:"merkle_root"`
Timestamp time.Time `json:"timestamp"`
}
ChainEntry is one line in the persistent JSONL file.
type MerkleTree ¶
type MerkleTree struct {
// contains filtered or unexported fields
}
MerkleTree implements a simple binary Merkle tree using SHA256. Leaves are added sequentially. The tree is rebuilt from scratch on every insertion so that the root hash is always current.
The tree is NOT thread-safe; callers must synchronize access.
func (*MerkleTree) AddLeaf ¶
func (t *MerkleTree) AddLeaf(data []byte) Hash
AddLeaf appends data as a new leaf node and returns its hash. The tree root is recomputed.
func (*MerkleTree) Leaves ¶
func (t *MerkleTree) Leaves() []Hash
Leaves returns a copy of all leaf hashes.
func (*MerkleTree) Proof ¶
func (t *MerkleTree) Proof(leafIndex int) ([]ProofStep, error)
Proof generates a Merkle inclusion proof for the leaf at leafIndex. The proof is the list of sibling hashes needed to reconstruct the root, ordered from the leaf level up toward the root. Each entry is accompanied by a direction flag: "left" means the proof hash is on the left (prepend it), "right" means the proof hash is on the right (append it).
Verification recomputes: hash = H(proof[i].Hash + hash) or hash = H(hash + proof[i].Hash) depending on the direction.
func (*MerkleTree) RootHash ¶
func (t *MerkleTree) RootHash() Hash
RootHash returns the current root hash of the tree. For an empty tree this returns the SHA256 of an empty byte slice.
func (*MerkleTree) Size ¶
func (t *MerkleTree) Size() int
Size returns the number of leaves in the tree.
Source Files