arpengine

package
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 28, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package arpengine sends unsolicited ARP replies on a cadence to perform MITM-style ARP poisoning, and emits corrective ARPs on stop.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActivePoison

type ActivePoison struct {
	Target  Target
	Started time.Time
}

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

func New(iface string, opMAC net.HardwareAddr, cadence time.Duration) (*Engine, error)

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

func (e *Engine) Close() error

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

func (e *Engine) Start(t Target) error

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

func (e *Engine) Stop(t Target) error

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

func (e *Engine) StopAll() error

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

func (e *Engine) StopAllWithContext(ctx context.Context) error

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

func (e *Engine) WriteFailures() int

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

func (e *Engine) WriteFrame(buf []byte) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL