Documentation
¶
Overview ¶
Package arpengine sends unsolicited ARP replies on a cadence to perform MITM-style ARP poisoning, and emits corrective ARPs on stop.
Index ¶
- type ActivePoison
- type Engine
- func (e *Engine) Active() []ActivePoison
- func (e *Engine) Close() error
- func (e *Engine) Start(t Target) error
- func (e *Engine) Stop(t Target) error
- func (e *Engine) StopAll() error
- func (e *Engine) StopAllWithContext(ctx context.Context) error
- func (e *Engine) WriteFailures() int
- func (e *Engine) WriteFrame(buf []byte) error
- type Target
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ActivePoison ¶
ActivePoison is the public view of an in-flight poison.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine manages the set of in-flight ARP poisons.
The engine owns a single shared pcap handle for all sends — both the per-target cadence loops and the post-stop corrective bursts. libpcap's WritePacketData is not goroutine-safe, so writes are serialised through handleMu. Per-target Open()/Close() in v1 was both expensive (N fd allocations + libpcap setup per Start) and racy with handle teardown during StopAll. Sharing one handle is faster, simpler, and removes the per-target failure mode of "couldn't open pcap for corrective".
func New ¶
New returns an engine bound to a specific interface and operator MAC. cadence=0 selects the default of 200ms (~5 fps × 4 frames/cycle = 20 frames/sec/target). This faster default is needed because modern devices (iOS 16+, Android 12+) refresh ARP entries sub-second when traffic is active. The original 1s default lost the cache race.
Operators on networks where 200ms is too aggressive for stealth can dial up via the daemon's -poison-cadence flag — `500ms` or `1s`. Note that slower cadence makes `policy clear` slower because the corrective has to flood harder to win the cache back.
Returns an error if the shared pcap handle can't be opened (most commonly: CAP_NET_RAW missing or iface doesn't exist). Callers should surface this at daemon startup so the operator gets a clear failure instead of a silent first-policy-fails-mysteriously later on.
func (*Engine) Active ¶
func (e *Engine) Active() []ActivePoison
Active returns a snapshot of in-flight poisons.
func (*Engine) Close ¶
Close releases the shared pcap handle. Idempotent. Should be called after StopAll() during daemon shutdown so any goroutine still trying to write through write() gets a clean error instead of a use-after-free.
func (*Engine) Start ¶
Start begins poisoning t. Idempotent: starting an already-active target is a no-op (returns nil without restarting).
Frame pre-build: the 4 frames sent on each cadence cycle are static for the lifetime of the runner, so they're constructed once here. A construction failure is surfaced as a Start error rather than being silently dropped per-tick — if gopacket can't serialise the frame for this target there's no point queuing the poison goroutine.
func (*Engine) Stop ¶
Stop halts poisoning of the named target and emits corrective ARPs asserting the real (gw,target) mappings. Blocks until the poison goroutine exits AND the corrective sequence completes — total wait is approximately 1.6 s (locktime + corrective burst). No-op for unknown targets.
func (*Engine) StopAll ¶
StopAll halts every active poison concurrently. The 1.1 s locktime sleep + 500 ms corrective burst is per-receiver, so running disjoint targets in parallel takes ~1.6 s total instead of N × 1.6 s. Errors are aggregated.
Why this matters: scripts/shardflow-up gives the daemon a 5-second SIGTERM grace window before SIGKILL. Sequential cleanup of 4+ active poisons would blow that budget and leave real victims poisoned.
func (*Engine) StopAllWithContext ¶ added in v1.1.1
StopAllWithContext is StopAll with an explicit context for cancellation. Used by the daemon to abort corrective bursts if SIGKILL escalates.
func (*Engine) WriteFailures ¶ added in v1.1.1
WriteFailures returns the total number of targets currently experiencing consecutive pcap write failures. A count > 0 with poisons active means ARP frames are not leaving the wire — throttle/drop/pcap policies are installed but the targets never see the poison.
func (*Engine) WriteFrame ¶
WriteFrame is the exported form of write. Lets other components on the daemon side (active.Sweep, future passive injectors) push frames through the engine's already-open pcap handle instead of opening a second write handle on the same iface — saves a pcap_activate + kernel ring buffer per use site.
Concurrency: serialised through handleMu (libpcap's WritePacketData is not goroutine-safe). Returns an error if the engine has been Closed.
type Target ¶
type Target struct {
MAC net.HardwareAddr
IP net.IP
GwMAC net.HardwareAddr
GwIP net.IP
}
Target is one host being poisoned. The same struct is used by policycompiler (which imports this package for the type) so the public field names match the compiler's call sites.