Documentation
¶
Overview ¶
Package audit provides query functions for the exclusion audit log.
Package audit provides structured logging for security-sensitive operations.
Package audit provides query functions for the audit log.
Index ¶
- func LogExclusionInline(operation, provider, repoFullName, operator, reason string, rowsAffected int64, ...)
- type AuditRecord
- type Event
- type ExclusionAuditQuerier
- func (q *ExclusionAuditQuerier) CountExclusionAuditLogs(ctx context.Context, opts ExclusionAuditQueryOptions) (int64, error)
- func (q *ExclusionAuditQuerier) GetActiveExclusions(ctx context.Context) ([]ExclusionAuditRecord, error)
- func (q *ExclusionAuditQuerier) GetActorAuditHistory(ctx context.Context, actor string, offset, limit int) ([]ExclusionAuditRecord, error)
- func (q *ExclusionAuditQuerier) GetLongstandingExclusions(ctx context.Context, minDuration time.Duration) ([]LongstandingExclusionV2, error)
- func (q *ExclusionAuditQuerier) GetRepoAuditHistory(ctx context.Context, repoID int64, offset, limit int) ([]ExclusionAuditRecord, error)
- func (q *ExclusionAuditQuerier) QueryExclusionAuditLogs(ctx context.Context, opts ExclusionAuditQueryOptions) ([]ExclusionAuditRecord, error)
- type ExclusionAuditQueryOptions
- type ExclusionAuditRecord
- type Logger
- type LongstandingExclusion
- type LongstandingExclusionV2
- type Querier
- func (q *Querier) GetActiveExclusions(ctx context.Context) ([]AuditRecord, error)
- func (q *Querier) GetAuditHistory(ctx context.Context, provider, repoFullName string, limit int) ([]AuditRecord, error)
- func (q *Querier) GetLongstandingExclusions(ctx context.Context, minDuration time.Duration) ([]LongstandingExclusion, error)
- func (q *Querier) GetOperatorHistory(ctx context.Context, operator string, limit int) ([]AuditRecord, error)
- func (q *Querier) GetRecentAuditLog(ctx context.Context, limit int) ([]AuditRecord, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LogExclusionInline ¶
func LogExclusionInline(operation, provider, repoFullName, operator, reason string, rowsAffected int64, incidentID string)
LogExclusionInline is a convenience function for logging without a Logger instance. This is useful for quick scripts that don't want to manage a logger.
Types ¶
type AuditRecord ¶
type AuditRecord struct {
ID int64
Timestamp time.Time
Operation string
Provider string
RepoFullName string
Operator string
Reason string
IncidentID string
ExcludedBefore *time.Time
ReasonBefore string
ExcludedAfter *time.Time
ReasonAfter string
RowsAffected int
}
AuditRecord represents a row from the audit_log table.
type Event ¶
type Event struct {
Timestamp time.Time `json:"timestamp"`
Operation string `json:"operation"` // "exclude" or "clear"
Provider string `json:"provider"`
RepoFullName string `json:"repo_full_name"`
Operator string `json:"operator"` // who performed the action
Reason string `json:"reason"` // why (exclusion reason or empty for clear)
RowsAffected int64 `json:"rows_affected"` // 1 if repo existed, 0 if not found
IncidentID string `json:"incident_id,omitempty"` // optional incident tracking
}
Event represents a single audit log event.
type ExclusionAuditQuerier ¶
type ExclusionAuditQuerier struct {
// contains filtered or unexported fields
}
ExclusionAuditQuerier provides query functions for the exclusion_audit_log table.
func NewExclusionAuditQuerier ¶
func NewExclusionAuditQuerier(db *sql.DB) *ExclusionAuditQuerier
NewExclusionAuditQuerier creates a new exclusion audit log querier.
func (*ExclusionAuditQuerier) CountExclusionAuditLogs ¶
func (q *ExclusionAuditQuerier) CountExclusionAuditLogs(ctx context.Context, opts ExclusionAuditQueryOptions) (int64, error)
CountExclusionAuditLogs returns the total count of records matching the filter options. This is useful for pagination UI to show total pages.
func (*ExclusionAuditQuerier) GetActiveExclusions ¶
func (q *ExclusionAuditQuerier) GetActiveExclusions(ctx context.Context) ([]ExclusionAuditRecord, error)
GetActiveExclusions retrieves all currently active exclusions from the exclusion audit log.
This returns repos that have an exclude event without a subsequent unexclude event. Returns the most recent audit record for each actively excluded repo.
func (*ExclusionAuditQuerier) GetActorAuditHistory ¶
func (q *ExclusionAuditQuerier) GetActorAuditHistory(ctx context.Context, actor string, offset, limit int) ([]ExclusionAuditRecord, error)
GetActorAuditHistory retrieves audit history for a specific actor.
Returns audit records performed by the given actor, ordered by timestamp descending (most recent first). Use offset and limit for pagination.
func (*ExclusionAuditQuerier) GetLongstandingExclusions ¶
func (q *ExclusionAuditQuerier) GetLongstandingExclusions(ctx context.Context, minDuration time.Duration) ([]LongstandingExclusionV2, error)
GetLongstandingExclusions finds repositories that have been excluded for longer than the specified duration without an unexclude event.
This is the key function for periodic alerting on the "reactive exclusion" residual risk described in plan.md's threat model. It surfaces repos that may have been excluded and forgotten, requiring review.
Joins with repos table to get provider and repo_full_name for display.
func (*ExclusionAuditQuerier) GetRepoAuditHistory ¶
func (q *ExclusionAuditQuerier) GetRepoAuditHistory(ctx context.Context, repoID int64, offset, limit int) ([]ExclusionAuditRecord, error)
GetRepoAuditHistory retrieves audit history for a specific repository.
Returns audit records for the given repository ID, ordered by timestamp descending (most recent first). Use offset and limit for pagination.
func (*ExclusionAuditQuerier) QueryExclusionAuditLogs ¶
func (q *ExclusionAuditQuerier) QueryExclusionAuditLogs(ctx context.Context, opts ExclusionAuditQueryOptions) ([]ExclusionAuditRecord, error)
QueryExclusionAuditLogs retrieves audit log records with filtering and pagination.
Returns audit records matching the provided options, ordered by timestamp descending (most recent first). Use Offset and Limit in options for pagination.
type ExclusionAuditQueryOptions ¶
type ExclusionAuditQueryOptions struct {
// RepoID filters to a specific repository (0 = all repos)
RepoID int64
// Actor filters to a specific actor (empty = all actors)
Actor string
// EventType filters to a specific event type ('exclude' or 'unexclude', empty = all)
EventType string
// DateRange filters by timestamp (zero values = no filter)
StartDate time.Time
EndDate time.Time
// Pagination controls
Offset int // Offset for pagination (0 = first page)
Limit int // Limit results (0 = use default of 100)
}
ExclusionAuditQueryOptions provides filtering and pagination for audit queries.
type ExclusionAuditRecord ¶
type ExclusionAuditRecord struct {
ID int64
RepoID int64
Actor string
Timestamp time.Time
EventType string // 'exclude' or 'unexclude'
OldExcludedAt *time.Time
OldExcludedReason *string
NewExcludedAt *time.Time
NewExcludedReason *string
}
ExclusionAuditRecord represents a row from the exclusion_audit_log table.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger writes structured audit logs for security-sensitive operations.
func NewLogger ¶
func NewLogger() *Logger
NewLogger creates a new audit logger that writes to stderr (or a configured output).
func (*Logger) LogExclusion ¶
LogExclusion logs an exclusion or clear operation to the audit log.
This feeds q-threat-exclusion-audit-log for incident response and postmortem analysis. Every exclusion/un-exclusion action must be logged with who/when/why.
type LongstandingExclusion ¶
type LongstandingExclusion struct {
Provider string
RepoFullName string
ExcludedAt time.Time
Reason string
LastAuditTime time.Time
Duration time.Duration // how long it's been excluded
Operator string // who applied the exclusion
}
LongstandingExclusion represents a repository that has been excluded for a long time.
type LongstandingExclusionV2 ¶
type LongstandingExclusionV2 struct {
RepoID int64
Provider string
RepoFullName string
ExcludedAt time.Time
Reason string
LastAuditTime time.Time
Duration time.Duration // how long it's been excluded
Actor string // who applied the exclusion
}
LongstandingExclusionV2 represents a repository that has been excluded for a long time. This version uses the exclusion_audit_log table with repo_id foreign key.
type Querier ¶
type Querier struct {
// contains filtered or unexported fields
}
Querier provides query functions for the audit log.
func (*Querier) GetActiveExclusions ¶
func (q *Querier) GetActiveExclusions(ctx context.Context) ([]AuditRecord, error)
GetActiveExclusions retrieves all currently active exclusions from the audit log.
This returns repos that have an exclude event without a subsequent clear event.
func (*Querier) GetAuditHistory ¶
func (q *Querier) GetAuditHistory(ctx context.Context, provider, repoFullName string, limit int) ([]AuditRecord, error)
GetAuditHistory retrieves audit history for a specific repository.
Returns audit records for the given repository, ordered by timestamp descending (most recent first). Use limit to control the number of records returned.
func (*Querier) GetLongstandingExclusions ¶
func (q *Querier) GetLongstandingExclusions(ctx context.Context, minDuration time.Duration) ([]LongstandingExclusion, error)
GetLongstandingExclusions finds repositories that have been excluded for longer than the specified duration without a clear event.
This is the key function for periodic alerting on the "reactive exclusion" residual risk described in plan.md's threat model. It surfaces repos that may have been excluded and forgotten, requiring review.
func (*Querier) GetOperatorHistory ¶
func (q *Querier) GetOperatorHistory(ctx context.Context, operator string, limit int) ([]AuditRecord, error)
GetOperatorHistory retrieves audit history for a specific operator.
Returns audit records performed by the given operator, ordered by timestamp descending (most recent first). Use limit to control the number of records returned.
func (*Querier) GetRecentAuditLog ¶
GetRecentAuditLog retrieves recent audit events across all repositories.
Returns audit records ordered by timestamp descending (most recent first). Use limit to control the number of records returned.
Source Files