● 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 / live / events.go
← Back to directory
151 lines · 5.8 KB
Raw
1package live
2
3import (
4 "time"
5
6 "github.com/shehzade/contraband/pkg/common"
7)
8
9// EventType categorizes real-time dashboard events.
10type EventType string
11
12const (
13 EventSessionStart EventType = "session_start"
14 EventConnectionOpen EventType = "connection_open"
15 EventChunkProgress EventType = "chunk_progress"
16 EventChunkReceived EventType = "chunk_received"
17 EventSessionComplete EventType = "session_complete"
18 EventProbeReceived EventType = "probe_received"
19 EventRateTick EventType = "rate_tick"
20 EventReportUploaded EventType = "report_uploaded"
21 EventProtocolStatus EventType = "protocol_status"
22 EventPortStatus EventType = "port_status"
23 EventCredentialCaptured EventType = "credential_captured"
24 EventHeartbeat EventType = "heartbeat"
25 EventDashboardReset EventType = "dashboard_reset"
26)
27
28// LiveEvent represents an individual telemetry event emitted over SSE.
29type LiveEvent struct {
30 ID string `json:"id"`
31 Type EventType `json:"type"`
32 Timestamp time.Time `json:"timestamp"`
33 TimestampMS float64 `json:"timestamp_ms"`
34 SessionID string `json:"session_id,omitempty"`
35 NetworkZone string `json:"network_zone,omitempty"`
36 ClientHost string `json:"client_host,omitempty"`
37 ClientIP string `json:"client_ip,omitempty"`
38 Protocol string `json:"protocol,omitempty"`
39 Message string `json:"message"`
40 Data interface{} `json:"data,omitempty"`
41}
42
43// SessionProgressData carries active stream metrics for EventChunkProgress.
44type SessionProgressData struct {
45 SessionID string `json:"session_id"`
46 NetworkZone string `json:"network_zone"`
47 ClientHost string `json:"client_host"`
48 ClientIP string `json:"client_ip"`
49 Protocol string `json:"protocol"`
50 Port int `json:"port,omitempty"`
51 Sequence uint32 `json:"sequence"`
52 TotalChunks uint32 `json:"total_chunks"`
53 BytesTransferred int64 `json:"bytes_transferred"`
54 TotalBytes int64 `json:"total_bytes"`
55 ProgressPct float64 `json:"progress_pct"`
56 InstantMBs float64 `json:"instant_mbs"`
57 RollingHash string `json:"rolling_hash,omitempty"`
58 ElapsedMS float64 `json:"elapsed_ms"`
59}
60
61// SessionCompleteData carries final completion metrics for EventSessionComplete.
62type SessionCompleteData struct {
63 SessionID string `json:"session_id"`
64 NetworkZone string `json:"network_zone"`
65 ClientHost string `json:"client_host"`
66 ClientIP string `json:"client_ip"`
67 Protocol string `json:"protocol"`
68 Port int `json:"port,omitempty"`
69 TotalBytes int64 `json:"total_bytes"`
70 TotalChunks int `json:"total_chunks"`
71 DurationMS float64 `json:"duration_ms"`
72 AverageMBs float64 `json:"average_mbs"`
73 FinalHash string `json:"final_hash"`
74 HashMatched bool `json:"hash_matched"`
75 Verdict common.Verdict `json:"verdict"`
76}
77
78// ReportUploadData carries high-level metrics for EventReportUploaded.
79type ReportUploadData struct {
80 ReportID string `json:"report_id"`
81 TargetHost string `json:"target_host"`
82 NetworkZone string `json:"network_zone"`
83 ClientHost string `json:"client_host"`
84 ClientIP string `json:"client_ip"`
85 EEIScore float64 `json:"eei_score"`
86 Posture string `json:"posture"`
87 TotalProbes int `json:"total_probes"`
88 SuccessCount int `json:"success_count"`
89 BlockedL4 int `json:"blocked_l4"`
90 BlockedL7 int `json:"blocked_l7"`
91 BlockedDLP int `json:"blocked_dlp"`
92 UploadedAt string `json:"uploaded_at"`
93}
94
95// ProbeData carries probe telemetry for EventProbeReceived.
96type ProbeData struct {
97 ProbeID string `json:"probe_id"`
98 NetworkZone string `json:"network_zone"`
99 ClientHost string `json:"client_host"`
100 ClientIP string `json:"client_ip"`
101 Protocol string `json:"protocol"`
102 TargetPort int `json:"target_port"`
103 Verdict common.Verdict `json:"verdict"`
104 TimestampMS float64 `json:"timestamp_ms"`
105}
106
107// ConnectionOpenData carries connection telemetry for EventConnectionOpen.
108type ConnectionOpenData struct {
109 SessionID string `json:"session_id,omitempty"`
110 NetworkZone string `json:"network_zone"`
111 ClientHost string `json:"client_host"`
112 ClientIP string `json:"client_ip"`
113 Protocol string `json:"protocol"`
114 Port int `json:"port"`
115 TimestampMS float64 `json:"timestamp_ms"`
116}
117
118// RateTickData carries sliding-window throughput telemetry for EventRateTick.
119type RateTickData struct {
120 InstantThroughputMBs float64 `json:"instant_throughput_mbs"`
121 PeakThroughputMBs float64 `json:"peak_throughput_mbs"`
122 ActiveStreams int `json:"active_streams"`
123 TotalBytes int64 `json:"total_bytes"`
124 TimestampMS float64 `json:"timestamp_ms"`
125}
126
127// PortStatus tracks individual port listening and traffic state for port status matrix.
128type PortStatus struct {
129 Port int `json:"port"`
130 Protocol string `json:"protocol"` // "TCP" or "UDP"
131 Service string `json:"service"` // "HTTP", "HTTPS", "DNS", "Reflector", etc.
132 Status string `json:"status"` // "listening", "receiving", "blocked", "idle", "reflection"
133 BytesRecv int64 `json:"bytes_recv"`
134 ProbesRecv int64 `json:"probes_recv"`
135 LastActive time.Time `json:"last_active"`
136}
137
138// DashboardResetData carries reset confirmation metadata for EventDashboardReset.
139type DashboardResetData struct {
140 DeletedFiles bool `json:"deleted_files"`
141 EvidenceDir string `json:"evidence_dir,omitempty"`
142 TimestampMS float64 `json:"timestamp_ms"`
143}
144
145// SafePrefix safely truncates a string to at most maxLen characters without panicking.
146func SafePrefix(s string, maxLen int) string {
147 if len(s) <= maxLen {
148 return s
149 }
150 return s[:maxLen]
151}