DEV Community: Marcin

On the wire: network traffic analysis and detection engineering with open tools

Marcin — Sat, 08 Aug 2026 16:08:06 +0000

Most write-ups about network security tools stop at "here are the flags." That is the least interesting part. The interesting part is the reasoning: you have a capture or a live sensor, you have a question — did this host get owned, and how would I know? — and you need to turn a wall of packets into an answer you can defend.

This article walks through the toolchain I actually use for that, in the order I usually reach for it: capture and triage with tcpdump and tshark, flow-level context with SiLK, protocol reconstruction with Zeek, signature detection with Snort and Suricata, and packet crafting with Scapy to test your own rules. The second half is dedicated to writing detection rules, from a one-line signature to entropy-aware DNS tunneling checks.

Every command here is copy-paste ready. The companion cheat sheets for each tool live in the same repository.

The toolkit at a glance

Each tool answers a different question. Reaching for the wrong one is how you burn an afternoon.

Tool	The question it answers
tcpdump	"Show me packets matching this precisely."
tshark	"Decode and extract fields from a protocol."
SiLK	"Who talked to whom, how much, over what period?"
Zeek	"Give me structured logs of everything that happened."
Snort / Suricata	"Alert me when traffic matches a known-bad pattern."
Scapy	"Let me build a packet by hand and send it."

Capture is the raw material. Flow data is the map. Zeek logs are the timeline. Signatures are the verdict. Scapy is your test harness. Keep those roles separate in your head and the workflow falls into place.

Part 1 — Capture and first triage

tcpdump is the tool you never fully outgrow. Its power is the Berkeley Packet Filter (BPF) language: you can express, before a single packet is decoded, exactly what you want to see.

Start simple — read a file, skip name resolution (which is slow and can leak lookups), and drop timestamps for cleaner grep-able output:

tcpdump -r capture.pcap -n
tcpdump -r capture.pcap -ntc 20        # first 20 records only
tcpdump -r capture.pcap -nX 'dst host 10.10.10.5 and src port 4444'

The -X flag prints hex and ASCII side by side, which is enough to eyeball a plaintext C2 beacon or a suspicious user agent without opening Wireshark.

Filtering on the bits, not just the fields

Where BPF earns its keep is reaching into header bytes directly. The TCP flags live in a single byte, tcp[13]:

Bit	7	6	5	4	3	2	1	0
Flag	CWR	ECE	URG	ACK	PSH	RST	SYN	FIN
Hex	0x80	0x40	0x20	0x10	0x08	0x04	0x02	0x01

To find connection attempts — SYN set, ACK not set — mask off the two high bits and compare:

tcpdump -r capture.pcap -n 'tcp[13] & 0x3f = 0x02'

Chain that into a quick top-ports summary and you have a horizontal-scan detector in one line:

tcpdump -r capture.pcap -n 'tcp[13] & 0x3f = 0x02' \
  | cut -d ' ' -f 5 | cut -d . -f 5 | sort | uniq -c | sort -nr | head

The same byte-offset trick works on DNS. A DNS message rides in the UDP payload, and since the UDP header is 8 bytes, the DNS header starts at udp[8]. That fixes the offsets you care about:

DNS field	UDP offset
Flags	`udp[10:2]`
Questions (QDCOUNT)	`udp[12:2]`
Answers (ANCOUNT)	`udp[14:2]`
Authority (NSCOUNT)	`udp[16:2]`
Additional (ARCOUNT)	`udp[18:2]`

The high bit of udp[10] is the QR flag: 0 for a query, 1 for a response. So "all DNS queries" and "all DNS responses" are:

tcpdump -r dns.pcap -n 'dst port 53 and udp[10] & 0x80 = 0'      # queries
tcpdump -r dns.pcap -n 'src port 53 and udp[10] & 0x80 = 0x80'   # responses

This is worth doing by hand once, even though Zeek and Suricata will parse DNS for you later. Understanding where the bits are is what lets you write good rules — and debug the ones that do not fire.

tshark when you need the parsed field

tcpdump filters on raw structure. tshark understands protocols, so you can pull named fields straight into columns — perfect for feeding a spreadsheet or another script:

tshark -r dns.pcap -n -Y 'udp.port == 53' \
  -T fields -e ip.src -e ip.dst -e dns.qry.name -e dns.a

Two tshark features I use constantly: stream numbers to isolate a conversation, and follow to dump one stream as text:

tshark -r capture.pcap -n -Y 'tcp.port == 25' -T fields -e tcp.stream | uniq
tshark -r capture.pcap -n -q -z follow,tcp,ascii,9 | less

Part 2 — Flow-level context with SiLK

Packets are detail; flows are perspective. When you are staring at gigabytes and do not yet know what matters, NetFlow tells you who talked to whom, how much, and when — without the payload.

SiLK's rwfilter selects flows and pipes them to rwcut for display:

rwfilter --type=all --start 2024/01/01 --end 2024/12/31 \
  --proto=6 --dport=443 --pass=stdout \
  | rwcut --fields=sip,sport,dip,dport,bytes --no-columns

The pattern that pays off in an investigation is chaining filters to answer a real question — for example, "what leaves my internal subnets but does not land in another internal subnet?" (i.e. traffic actually heading out):

rwfilter --type=all --start 2024/01/01 --end 2024/12/31 \
  --scidr=10.200.0.0/16 --proto=6 --pass=stdout \
  | rwfilter --dcidr=10.200.0.0/16 --fail=stdout --input-pipe=stdin \
  | rwcut --fields=sip,sport,dip,dport,bytes,flags --no-columns

The trick is --input-pipe=stdin on the second rwfilter, and --fail to keep only the flows that did not match the internal destination. For top-talker summaries, rwstats does the counting for you.

Part 3 — Turning packets into evidence with Zeek

Zeek is the tool that changed how I read traffic. Instead of decoding packets, it produces structured, tab-separated logs — conn.log, dns.log, http.log, ssl.log, files.log, x509.log — and stitches them together with a shared connection id (uid). Find one interesting record and you can pivot to every other log entry for the same connection.

zeek -r capture.pcap                          # generates *.log in the cwd
cat http.log | zeek-cut -u ts uid id.orig_h id.resp_h host uri status_code

zeek-cut extracts named columns (the -u renders timestamps in UTC). Chasing a file by its id across every log is a one-liner:

grep FYAp0L1VyrDDhX8uu *.log

Beyond logging, Zeek is programmable. You can write scripts that react to events — extract every file carried over HTTP, flag a DNS answer that points at a domain you saw in an email, and so on. That scripting layer is where Zeek stops being a logger and becomes a detection platform, but even the default logs alone are worth the setup.

Part 4 — Signature detection: Snort and Suricata

Snort and Suricata both match traffic against rules and raise alerts. Suricata is multi-threaded and speaks the richer, more modern rule syntax, so the rule-writing section below uses it — but the two dialects are close cousins.

Run Suricata over a pcap and point it at your ruleset:

suricata -T -c suricata.yaml -S local.rules -vvv        # validate config + rules
suricata -r sample.pcap -c suricata.yaml -S local.rules -l ./logs/

Alerts and protocol events land in logs/eve.json in EVE format — JSON, one event per line, which means jq is your query engine:

jq -c 'select(.event_type=="alert") | {sig: .alert.signature, src: .src_ip, dst: .dest_ip}' logs/eve.json

Note that the signature id is nested under the alert object as .alert.signature_id, not at the top level — a small detail that quietly returns null if you get it wrong.

Snort's equivalents are worth knowing when you land on a Snort box:

snort -r sample.pcap -c snort.lua -q -A alert_fast -R local.rules

Part 5 — Writing detection rules, simple to advanced

This is the part that separates using an IDS from operating one. We will start from a rule you can read at a glance and finish with stateful, intel-backed detection that reasons about byte layout and entropy. Along the way, the rules pick up the scaffolding that distinguishes a lab example from something you would actually deploy: precise buffers, a fast-pattern anchor, MITRE-tagged metadata, tuning, and a lifecycle.

Anatomy of a rule

Every Suricata rule has three parts: an action, a header, and options in parentheses.

action protocol src_ip src_port -> dst_ip dst_port (options)

Action — alert (log it), drop (block, IPS mode), reject (block and tear down), pass (allow, stop evaluating).
Header — the protocol (tcp, udp, dns, http, tls, …), addresses and ports, and direction (-> or <>). $HOME_NET and $EXTERNAL_NET are variables defined in suricata.yaml.
Options — the detection logic plus the metadata that makes a rule maintainable.

A rule with no msg, no classtype, no reference, and no metadata will still fire — and it will be worthless six months later when an analyst triages the alert and has no idea what it means or how confident to be. Treat metadata as part of the detection, not decoration.

Level 1 — a precise, documented first rule

The textbook version of a first rule is "match a bad hostname." The deployable version scopes the flow, anchors the fast pattern, pins the buffer length, and carries enough context to triage:

alert http $HOME_NET any -> $EXTERNAL_NET any ( \
    msg:"MALWARE Outbound HTTP to known-bad C2 host"; \
    flow:established,to_server; \
    http.host; content:"evil.example.com"; fast_pattern; bsize:16; \
    classtype:trojan-activity; \
    reference:url,attack.mitre.org/techniques/T1071/001/; \
    metadata:attack_target Client_Endpoint, deployment Perimeter, \
      signature_severity Major, confidence High, \
      mitre_tactic_id TA0011, mitre_technique_id T1071, \
      created_at 2024_01_10, updated_at 2024_01_10; \
    sid:1000001; rev:1;)

What earns each keyword its place:

flow:established,to_server — evaluate only the client-to-server side of an established session. This one keyword removes most false positives and a lot of wasted CPU.
bsize:16 — the http.host buffer must be exactly 16 bytes (evil.example.com), so a lookalike subdomain does not slip through and the match is unambiguous.
fast_pattern — tells the engine which content to load into the multi-pattern matcher for the first-pass filter. On a busy sensor, choosing a good fast pattern is the single biggest performance lever you have.
classtype / reference / metadata — the triage context: what kind of activity, where it maps in ATT&CK, how severe, and how much to trust it. Keep local sids in the 1000000+ range and bump rev on every edit.

Level 2 — content matching that performs

content is the workhorse; the modifiers are what make it precise and cheap. The goal is always to match the smallest, most specific buffer possible.

http.method; content:"POST";
http.uri; content:".php?id="; fast_pattern;
http.user_agent; content:"Mozilla/4.0 (compatible|3b 20|MSIE";
http.header_names; content:!"Referer"; content:!"Accept-Language";

offset / depth constrain where to look; distance / within position one content relative to the previous one — enough to parse structured payloads without paying for a regex.
Negation (content:!"...") is underused: a lot of automated clients give themselves away by the headers a real browser sends and they omit. Matching on http.header_names for absent Referer and Accept-Language is a classic, cheap C2 heuristic.
Bytes you cannot type go in pipes as hex: |3b 20| is "; ".
Put fast_pattern on the longest, rarest content — never on something like "GET" that appears in nearly every packet.

Level 3 — stateful detection: flowbits and xbits

Single-packet rules miss anything that unfolds over a conversation. flowbits carries state within a flow; xbits carries it across flows on the same host, which is how you correlate, say, a phishing click with a later beacon from the same endpoint.

Two-stage detection within one flow — a download request followed by an executable in the response — alerting only on the combination:

alert http $HOME_NET any -> $EXTERNAL_NET any ( \
    msg:"MALWARE Stage 1 suspicious payload request"; \
    flow:established,to_server; \
    http.uri; content:"/api/v1/getfile"; fast_pattern; \
    flowbits:set,payload.request; flowbits:noalert; \
    classtype:trojan-activity; sid:1000010; rev:1;)

alert http $EXTERNAL_NET any -> $HOME_NET any ( \
    msg:"MALWARE PE delivered after suspicious request"; \
    flow:established,to_client; \
    flowbits:isset,payload.request; \
    file.data; content:"MZ"; startswith; \
    content:"This program cannot be run in DOS mode"; distance:0; \
    classtype:trojan-activity; \
    metadata:mitre_tactic_id TA0011, mitre_technique_id T1105; \
    sid:1000011; rev:1;)

The first rule sets a bit and stays silent (noalert); the second fires only if that bit is set earlier in the same flow and the response actually carries a PE. Correlating across flows on a host looks the same, with xbits:set,name, track ip_src, expire 3600; and a matching xbits:isset.

Level 4 — protocol intelligence (DNS and TLS)

Modern detection lives in the parsed protocol buffers, and it shines on traffic you cannot read.

DNS — beaconing and tunneling. A single long query means little; many long, high-entropy queries to one parent domain in a short window is what exfiltration looks like. Combine a PCRE length/charset test with a threshold so you alert on the behavior, not on each packet:

alert dns $HOME_NET any -> any any ( \
    msg:"MALWARE Possible DNS tunneling - sustained long high-entropy labels"; \
    dns.query; \
    pcre:"/^[a-z0-9]{40,}\.[a-z0-9\-]+\.[a-z]{2,}$/i"; \
    threshold:type both, track by_src, count 15, seconds 60; \
    classtype:bad-unknown; \
    reference:url,attack.mitre.org/techniques/T1071/004/; \
    metadata:attack_target Client_Endpoint, deployment Perimeter, \
      signature_severity Major, confidence Medium, \
      mitre_tactic_id TA0011, mitre_technique_id T1071, \
      created_at 2024_01_10, updated_at 2024_01_10; \
    sid:1000020; rev:1;)

threshold:type both, count 15, seconds 60 means: only alert after 15 matches from the same source within a minute, then at most once per window. That is the line between a signal and an alert storm. Pair it with hunting for a burst of NXDOMAIN responses in the DNS logs, which DGA and tunneling both generate heavily.

When you do want an exact domain — say, matching a C2 domain but not a lookalike subdomain of it — two keywords make it airtight. bsize pins the buffer length, and dotprefix prepends a . to the query buffer so an endswith cannot be fooled by evilcdn.example.com when you meant cdn.example.com:

alert dns $HOME_NET any -> any any ( \
    msg:"MALWARE C2 domain lookup"; \
    dns.query; dotprefix; content:".cdn.example.com"; endswith; \
    classtype:trojan-activity; sid:1000021; rev:1;)

TLS — fingerprint what you cannot decrypt. The payload is encrypted, but the handshake is not: the SNI, the certificate subject/issuer, and the JA3/JA3S fingerprints are all in the clear and remarkably identifying (JA3 must be enabled under the TLS parser in suricata.yaml).

alert tls $HOME_NET any -> $EXTERNAL_NET any ( \
    msg:"MALWARE JA3 fingerprint matches known C2 client"; \
    ja3.hash; content:"a0e9f5d64349fb13191bc781f81f42e1"; \
    flow:established,to_server; \
    classtype:trojan-activity; \
    metadata:mitre_tactic_id TA0011, mitre_technique_id T1573, \
      signature_severity Major, confidence High; \
    sid:1000030; rev:1;)

At scale you do not write one rule per indicator. A dataset matches a buffer against an external list and stays fast with tens of thousands of entries — the right structure for threat-intel feeds of bad JA3 hashes or domains:

alert tls $HOME_NET any -> $EXTERNAL_NET any ( \
    msg:"MALWARE TLS JA3 on threat-intel list"; \
    ja3.hash; dataset:isset,bad_ja3, type string, load bad_ja3.lst; \
    flow:established,to_server; \
    classtype:trojan-activity; sid:1000031; rev:1;)

Level 5 — byte math for protocol and exploit detection

When detection depends on a value the protocol computes — a length field, a record count, an opcode — you need arithmetic on raw bytes. byte_extract pulls a value into a variable, byte_test compares against one, and byte_jump moves the cursor by a computed amount.

A generic "declared length is absurdly large" check — the shape of many buffer-overflow attempts against a length-prefixed protocol:

alert tcp $EXTERNAL_NET any -> $HOME_NET 1521 ( \
    msg:"EXPLOIT Oversized declared length field (possible overflow)"; \
    flow:established,to_server; \
    content:"|00 03|"; offset:0; depth:2; \
    byte_test:2, >, 4096, 2; \
    classtype:attempted-admin; \
    metadata:mitre_tactic_id TA0001, mitre_technique_id T1190; \
    sid:1000040; rev:1;)

Read byte_test:2, >, 4096, 2 as: take the 2-byte value at offset 2 and match if it is greater than 4096. Swap the operator for & to test individual flag bits (byte_test:1, &, 0x80, 3 matches when the high bit of the byte at offset 3 is set).

byte_jump is the keyword that makes length-prefixed protocols matchable: read a length field, then skip exactly that many bytes so the cursor lands on whatever comes after a variable-length blob. Consider a protocol shaped as [magic][2-byte length][payload of that length][command byte] — you want the command byte, but you cannot know its offset in advance:

alert tcp $HOME_NET any -> $EXTERNAL_NET any ( \
    msg:"MALWARE C2 command after variable-length field"; \
    flow:established,to_server; \
    content:"|aa bb|"; depth:2; \
    byte_jump:2, 0, relative; \
    content:"|01|"; distance:0; within:1; \
    classtype:trojan-activity; sid:1000042; rev:1;)

Step through it: content:"|aa bb|" matches the magic at the start and leaves the cursor at byte 2. byte_jump:2, 0, relative reads a 2-byte value at the cursor (the length field) and advances the cursor forward by that many bytes — over the whole variable payload. The final content:"|01|"; distance:0; within:1 then checks the single byte the cursor now points at. One rule, correct regardless of how long the payload is. Add multiplier N when the length is counted in words rather than bytes, or from_beginning to jump from the start of the buffer instead of the current position.

For proprietary binary C2 with no protocol parser to lean on, you match the wire bytes directly — and dsize (payload length) is a cheap, discriminating pre-filter. A fixed-size command header is a good example:

alert tcp $HOME_NET any -> $EXTERNAL_NET any ( \
    msg:"MALWARE Custom C2 fixed-size beacon"; \
    flow:established,to_server; dsize:16; \
    content:"|de ad be ef|"; depth:4; \
    content:"|01|"; distance:3; within:1; \
    classtype:trojan-activity; sid:1000041; rev:1;)

dsize:16 throws out everything that is not exactly a 16-byte payload before any content match runs — the kind of early bail-out that keeps a sensor fast.

Tuning out false positives

This is the discipline that separates a rule you wrote from a rule you can run. The pattern is always the same: keep the true positives, carve out the benign traffic that happens to look similar — without gutting the rule into uselessness.

The first tool is negation. If a legitimate host or client trips your hunting rule, exclude precisely that, and nothing more:

# Base hunting rule — a generic C2 gate, but a legit app also posts to /gate.php
alert http $HOME_NET any -> $EXTERNAL_NET any ( \
    msg:"HUNT Request to /gate.php"; \
    flow:established,to_server; \
    http.uri; content:"/gate.php"; \
    classtype:bad-unknown; sid:1000050; rev:1;)

# Same rule, minus the one benign app — note the rev bump
alert http $HOME_NET any -> $EXTERNAL_NET any ( \
    msg:"HUNT Request to /gate.php"; \
    flow:established,to_server; \
    http.uri; content:"/gate.php"; \
    http.host; content:!"updates.legit-vendor.com"; \
    classtype:bad-unknown; sid:1000050; rev:2;)

You can exclude on any buffer — a specific header the benign client sends (http.header; content:!"X-Requested-With: com.legit.app";), or the absence of one the malware never sets (http.header_names; content:!"User-Agent";).

The second tool is tightening the anchor. A short match at the wrong offset produces phantom hits. Suppose content:"Gh0st"; offset:8; depth:5; false-positives on unrelated traffic that happens to contain that string. Pin it to the byte that actually precedes it in the real protocol:

content:"|00|Gh0st"; offset:7; depth:6;

Same string, but now it only matches where a null byte sits immediately before it — the structural detail the coincidental traffic lacks. Every false positive is a lesson about a byte you were not yet constraining.

Making rules production-ready

A rule that matches is only half the job. Before it goes live:

Order for the early bail-out. Suricata evaluates cheap checks before expensive ones, so give it a reason to quit early: lead with dsize, flow, and a long content before any pcre. Never ship a regex-only rule — always pair pcre with at least one content the engine can reject on first. Profiling (--enable-profiling) shows you which rules are actually eating CPU.
Pick the fast pattern deliberately. Run suricata --engine-analysis and read rules_analysis.txt — it tells you which content Suricata chose as the fast pattern and warns about rules with weak or no anchor. Set fast_pattern on the longest, rarest content; a bad fast pattern is the usual cause of a sensor falling behind.
Tune, do not silence. If a rule is noisy, reach for threshold/detection_filter and tighter buffers before you disable it. An alert firing 5,000 times has told you nothing 4,999 times.
Version and source everything. rev, created_at/updated_at, and a reference are what let you manage rules at scale; suricata-update expects that discipline when it merges your local rules with feeds.
Right-size the action. Ship as alert first, watch it in production, and only promote a high-confidence rule to drop once you trust it — a false-positive drop is an outage.

Testing your rules before you trust them

A rule you have not tested is a hypothesis, not a control. This is where Scapy closes the loop: craft the exact packet your rule should catch, replay it, and confirm the alert.

from scapy.all import *

pkt = IP(dst="10.0.0.53")/UDP(dport=53)/DNS(
        rd=1, qd=DNSQR(qname="a"*45 + ".exfil.example"))
wrpcap("test_tunnel.pcap", pkt)

suricata -r test_tunnel.pcap -c suricata.yaml -S local.rules -l ./logs/
jq -c 'select(.event_type=="alert").alert.signature' logs/eve.json

One caveat worth internalizing: if you edit a field on a packet Scapy already built, it does not recompute checksums until it re-serializes. Read such a doctored pcap back with tcpdump -v and you will see bad cksum. That is expected — Scapy fixes the checksum on send, not on assignment.

Part 6 — Tying it together

A realistic investigation is not one tool; it is a relay:

Reduce with SiLK — find the handful of flows that are anomalous by volume, timing, or destination.
Reconstruct with Zeek — pull the DNS, HTTP, and TLS logs for those hosts and build a timeline off the shared uid.
Confirm with tcpdump/tshark — carve the exact packets and read the payload where it is not encrypted.
Operationalize with Suricata — encode what you found as a rule so the next occurrence pages you instead of hiding in a pcap.
Verify with Scapy — replay a synthetic version of the attack and prove the rule fires.

Detection engineering is that last step done deliberately. Every incident should leave behind a tested rule, so your coverage compounds instead of resetting with each investigation.

Pitfalls I learned the slow way

Match parsed fields, not raw payload, whenever a buffer exists. http.host; content:"x" is precise and fast; a bare content:"x" scans everything and misfires.
Scope with flow. Most noisy rules are noisy because they match both directions or unestablished traffic.
Threshold high-frequency signals. A rule that fires 5,000 times has told you nothing 4,999 times.
Know your offsets. DNS additional records are udp[18:2], not the question count (udp[12:2]). A rule built on the wrong offset looks fine and silently never matches.
Test with real bytes. Craft the packet, replay it, read the alert. Trust nothing you have not seen fire.

Self-hosting Agentless EDR -bladedr 0.9.0: what works and what is still beta

Marcin — Mon, 27 Jul 2026 19:59:44 +0000

description: "A practical look at bladedr, its agentless Linux scanning model, current limits, and a Docker Compose deployment."

This post covers
v0.9.0, released on
July 27, 2026. I pulled the published image, ran its key generator, started the
server, checked its health endpoints, and logged in. I also checked the commands
below against the tagged repository.

I have not audited the code or run bladedr on a production fleet. The eBPF
sensor and response actions are marked Beta by the project. Risk scoring is
experimental.

What bladedr does

bladedr scans Linux hosts over SSH. The
server uploads a static binary called bladedr-probe, runs it on the target,
and receives the findings as JSON. The probe reads a snapshot of system state,
including data from /proc, and evaluates detection rules written in YAML and
CEL.

There is no daemon running on the target between agentless scans. The uploaded
probe is cached under /tmp/.bladedr/, so "agentless" does not mean that the
scan leaves no file behind. It means there is no resident process, package, or
kernel module in the default scanning mode.

The optional eBPF tier is different. bladedr-sensor is a long-running service
that wraps Tetragon. It requires root, Docker, and a kernel that supports BTF.

The project has four main binaries:

bladedr-server: API, web console, inventory, scan scheduling, and storage;
bladedr-probe: the program executed during an SSH scan;
bladectl: a command-line API client;
bladedr-sensor: the optional Tetragon event forwarder.

The mar0ls/bladedr:0.9.0 image supports linux/amd64 and linux/arm64. It
contains probe and sensor binaries for both architectures. The server can
therefore scan either architecture without a Go toolchain on the control-plane
host. Version 0.9.0 reports 87 built-in detection rules at startup.

The rules are data rather than compiled Go code. Filesystem and database rules
can extend or override the built-in YAML and CEL rules. The server also tracks
per-host baselines, reports drift, calculates fleet rarity, supports triage and
audit logging, and exports ECS/JSON records.

The limit of an SSH snapshot

An SSH scan only sees state that exists while the probe is running. A short
process or network connection can start and stop between scans without being
observed. Continuous telemetry needs the optional sensor tier or another
runtime monitoring tool.

The project publishes a
coverage matrix.
It lists implemented detections and known gaps. A successful installation does
not imply complete detection coverage.

The SSH account also affects visibility. The probe can run without root, but an
unprivileged account cannot read all system data. Giving the control plane root
SSH credentials improves visibility while increasing the impact of a control
plane compromise.

What is not stable yet

The project's
stability document
uses three levels:

agentless SSH scanning, storage, authentication, the rule engine, and the v1 API are listed as GA;
the eBPF sensor, server-push sensor deployment, response actions, and bladectl are Beta;
learned risk scoring, attack-emulation training, and retention are experimental.

The image does not ship with Tetragon policies. /etc/bladedr/policies is
empty. Enabling the sensor requires an operator-supplied TracingPolicy
bundle.

Response actions run fixed, allowlisted playbooks instead of accepting arbitrary
shell commands. They require approval from a second administrator by default.
They are still Beta, and the project says they have not been proven on a real
fleet. A bad isolate_host configuration can cut a machine off from the
control plane.

Risk scoring only changes the order of findings. It does not generate
detections or suppress an observation.

There is one stale sentence in the tagged stability document. It says the
release workflow does not publish an image and that Docker Hub is not wired up.
The public 0.9.0 image exists and can be pulled, so that note no longer matches
the release.

Deploying the control plane

The repository includes a Compose file for the server and its database. This
setup uses:

mar0ls/bladedr:0.9.0;
paradedb/paradedb:0.23.5;
a named volume for the database;
a server port bound to 127.0.0.1.

ParadeDB is used because observation search depends on the BM25 index provided
by pg_search. Stock PostgreSQL is not the documented production backend.
Without BLADEDR_DATABASE_URL, bladedr uses an in-memory store and loses its
state on restart.

Download the tagged Compose file

mkdir bladedr-deploy
cd bladedr-deploy

curl -fsSLo compose.yml \
  https://raw.githubusercontent.com/mar0ls/bladedr/v0.9.0/docs/compose.example.yml

The file pins version 0.9.0. The public image index had this digest when I
checked it:

sha256:78533b520303373beb9d97b382d4aee9d173242428f5d67aa07dd19817041368

A version tag makes upgrades explicit. A digest is stricter because a registry
owner can move a tag, while the digest identifies the exact image content.
latest is fine for a temporary test, but I would not use it for this control
plane.

Generate the node key

docker run --rm mar0ls/bladedr:0.9.0 -keygen

The command prints BLADEDR_NODE_KEY and a public key. Save
BLADEDR_NODE_KEY. It decrypts stored SSH credentials. Losing it makes those
credentials unrecoverable, even if the database is intact. A database copy on
its own does not contain enough information to decrypt them.

Create the environment file

Generate a database password that is safe to place directly in a PostgreSQL
connection string:

openssl rand -hex 32
install -m 600 /dev/null .env

Edit .env:

BLADEDR_NODE_KEY=VALUE_PRINTED_BY_KEYGEN
POSTGRES_PASSWORD=RANDOM_HEX_PASSWORD

Do not commit this file. Keep a backup of the node key separately from the
database dump.

Start the stack

docker compose -f compose.yml up -d
docker compose -f compose.yml ps

The database port is not published on the host. The web server listens on
127.0.0.1:8080, using plain HTTP in this example.

Check readiness:

curl -fsS http://127.0.0.1:8080/readyz

Expected response:

{"status":"ready"}

/readyz also checks the data store. /healthz and /metrics are available
without authentication. Keep all three endpoints internal unless there is a
reason to expose them.

Get the initial admin password

On a fresh database, the server creates an admin account. If
BLADEDR_ADMIN_PASSWORD is not set, it generates a password and writes it to
the startup log:

docker compose -f compose.yml logs server

Open:

http://127.0.0.1:8080/ui/login

The generated password must be changed after the first login. It remains in the
container logs, so those logs should be treated as sensitive.

For a remote control-plane host, an SSH tunnel avoids publishing the plain HTTP
port:

ssh -N -L 8080:127.0.0.1:8080 operator@control-plane-host

The console will then be available on the local machine at
http://127.0.0.1:8080/ui/login.

For permanent access, terminate TLS in bladedr or at a reverse proxy. Direct TLS
uses BLADEDR_TLS_CERT and BLADEDR_TLS_KEY. When TLS terminates at a proxy,
set BLADEDR_SECURE_COOKIES=1. Configure BLADEDR_TRUSTED_PROXY_CIDRS as well;
otherwise forwarded client IP headers are ignored and login rate limiting and
audit records see the proxy address.

Adding a Linux host

The control plane needs outbound SSH access to the target. In the web console:

Open Hosts and expand Add host.
Enter the IP address, SSH port, username, and either a password or private key.
Select amd64 or arm64.
Keep the mode set to scan_only unless you have supplied Tetragon policies.
Add the host and click Scan.

The SSH secret is sealed with the node key before it is stored. The server pins
the SSH host key on first use. That is TOFU, so the first connection should take
place over a path you trust.

No repository checkout or compiler is required on the target. The server
uploads the probe included in its container image.

Backup and upgrades

Dump the database before an upgrade:

docker compose -f compose.yml exec -T db \
  pg_dump -U bladedr bladedr > bladedr-$(date +%F).sql

Back up BLADEDR_NODE_KEY separately. The dump and node key together are the
documented complete backup.

Database migrations run when the server starts. Downgrading to a version that
predates an applied migration is not supported. Read the
CHANGELOG.md
before changing the image version.

The 0.9.0 upgrade invalidates existing sessions and replaces the old shared
sensor token with per-host tokens. Its release notes say that hosts, scans,
observations, triage state, rules, baselines, credentials, and audit history are
preserved.

My take

Version 0.9.0 is usable for testing central SSH-based scans, writing CEL rules,
and checking how agentless detection fits a Linux environment. The published
image removes the need to compile the server and its architecture-specific
probes.

I would test it on disposable or non-production hosts first. The control plane
holds SSH access to the fleet, agentless scans have gaps between snapshots, and
the continuous sensor path does not yet include a policy bundle. Those are
important design and maturity limits, not installation details.

The source, tagged binaries, SBOM, checksums, and container image are public.
Start with the coverage matrix and compare it with the threats that matter in
your environment before granting access to production machines.

References

Managing System Proxy Settings in Go Across macOS, Linux, and Windows

Marcin — Sat, 25 Jul 2026 20:11:13 +0000

Picture this: you're writing a Go integration-test harness that must route all traffic through a corporate proxy during the test run, then leave the developer's machine exactly as it found it. You reach for HTTP_PROXY — and quickly discover that system-level proxy configuration is a different problem entirely.

On macOS you need networksetup. GNOME uses gsettings. KDE has its own tooling. Windows stores proxy settings in the registry. Add authentication, PAC files, cleanup, and error handling, and what looked like a one-afternoon feature becomes a collection of platform-specific scripts that nobody wants to maintain.

go-sysproxy wraps those native mechanisms in a single Go API. The rest of this article uses the test-harness scenario to walk through the library feature by feature — from a first proxy to full multi-protocol configuration, safe restore, and the CLI.

Verification scope: this article was checked against the tagged v0.5.2 source at commit 14e44f6. All public API examples were verified against the implementation, and go test ./... passes with Go 1.26.2 on darwin/arm64. Platform descriptions come from inspection of platform-specific source and unit tests; they are not presented as live integration-test results for every supported desktop and Windows version.

Installation

go-sysproxy requires Go 1.22 or newer and has no external Go module dependencies:

go get github.com/mar0ls/go-sysproxy

import sysproxy "github.com/mar0ls/go-sysproxy"

Your first system proxy

The shortest example sets a proxy, runs some code, then clears it:

package main

import (
    "log"
    sysproxy "github.com/mar0ls/go-sysproxy"
)

func main() {
    if err := sysproxy.Set("http://proxy.example.com:8080", sysproxy.ScopeGlobal); err != nil {
        log.Fatal(err)
    }
    defer func() {
        if err := sysproxy.Unset(sysproxy.ScopeGlobal); err != nil {
            log.Printf("could not clear proxy: %v", err)
        }
    }()

    // Run your network-aware code here.
}

Set accepts URLs with credentials:

http://username:password@proxy.example.com:8080
socks5://username:password@proxy.example.com:1080

For the test harness — where you want a hard deadline on how long a proxy change can take — the context-aware variant is the right choice:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

err := sysproxy.SetContext(ctx, "http://proxy.example.com:8080", sysproxy.ScopeGlobal)

The implementation checks an already-cancelled context before side effects. Command-backed operations use exec.CommandContext; this does not make a multi-step OS update transactional. The same pattern is available through UnsetContext, GetContext, GetConfigContext, SetMultiContext, and SetPACContext.

Choose the right scope

The Set call above used ScopeGlobal. The scope controls how far the change reaches:

Scope	What it changes	Typical use
`ScopeShell`	Proxy environment variables in the current process	One-off commands, child processes
`ScopeUser`	Current process plus shell startup files or the PowerShell profile	Persistent per-user development setup
`ScopeGlobal`	Current process plus the native OS proxy store	Desktop apps, VPN clients, proxy switchers

One nuance: ScopeGlobal is an API-level label, not a machine-wide guarantee. On Windows, the backend writes HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings, which is scoped to the current Windows user. On Linux, writing /etc/environment can require root. Get and GetConfig read the OS-level configuration, so they are intended for global proxy state, not shell or user-profile values.

For the integration-test scenario, ScopeGlobal is the right choice: it reaches desktop apps and other processes that read the native proxy store, which is exactly what you want when testing through a corporate gateway.

The safer pattern: apply, run, restore

The naive approach — Set at the start, Unset at the end — breaks the moment a developer already has a proxy configured. Your harness would clobber their setup and fail to restore it.

WithProxy solves this properly. It reads the current ProxyConfig, applies the temporary proxy, runs a callback, and then restores the previous state — regardless of whether the callback succeeds or fails:

err := sysproxy.WithProxy(
    ctx,
    "socks5://proxy.example.com:1080",
    sysproxy.ScopeGlobal,
    func(ctx context.Context) error {
        return runIntegrationTests(ctx)
    },
)

For ScopeGlobal, the snapshot is a full ProxyConfig containing HTTP, HTTPS, SOCKS, the bypass list, and PAC fields. The restore path reapplies PAC when PAC is non-empty; otherwise it reapplies the manual protocol fields, or calls Unset if none were set.

Two things to know about restore:

Restore errors are not returned to the caller. Critical failures go to the optional package logger instead. If your harness needs to detect a failed restore, install a logger and verify state with GetConfig afterward.
ScopeShell and ScopeUser do not have a read-back snapshot path. With those scopes, WithProxy calls Unset after the callback — it does not restore pre-existing environment or profile values.

Configure each protocol separately

A single proxy URL works for many cases. Corporate environments often require separate endpoints for HTTP, HTTPS, and SOCKS. SetMulti handles that:

err := sysproxy.SetMulti(sysproxy.ProxyConfig{
    HTTP:    "http://http-proxy.example.com:8080",
    HTTPS:   "http://https-proxy.example.com:8443",
    SOCKS:   "socks5://socks-proxy.example.com:1080",
    NoProxy: "localhost,127.0.0.1,10.0.0.0/8",
}, sysproxy.ScopeGlobal)

The implementation validates non-empty HTTP, HTTPS, and SOCKS URLs before starting side effects. Note that SetMulti does not apply the PAC field — use SetPAC for PAC mode. Backend behavior is not fully transactional: the Windows path, for example, enables ProxyEnable before writing the individual protocol entries.

There is a temporary multi-protocol variant too, with the same read-back restore semantics as WithProxy:

err := sysproxy.WithProxyMulti(
    ctx,
    sysproxy.ProxyConfig{
        HTTP:  "http://proxy.example.com:8080",
        HTTPS: "http://proxy.example.com:8080",
    },
    sysproxy.ScopeGlobal,
    func(ctx context.Context) error {
        return runIntegrationTests(ctx)
    },
)

Work with PAC files

Some networks distribute proxy configuration via Proxy Auto-Config files. To request PAC mode from the selected backend:

err := sysproxy.SetPAC(
    "https://config.example.com/proxy.pac",
    sysproxy.ScopeGlobal,
)

The validator accepts http://, https://, and file:// URLs. To inspect what is currently active:

cfg, err := sysproxy.GetConfig()
if err != nil {
    log.Fatal(err)
}

fmt.Printf("HTTP:    %s\n", cfg.HTTP)
fmt.Printf("HTTPS:   %s\n", cfg.HTTPS)
fmt.Printf("SOCKS:   %s\n", cfg.SOCKS)
fmt.Printf("NoProxy: %s\n", cfg.NoProxy)
fmt.Printf("PAC:     %s\n", cfg.PAC)

When automatic proxy configuration is active, PAC holds the URL. For manual mode, the individual protocol fields hold the configured endpoints.

Handle errors without parsing strings

System proxy configuration can be in several distinct states: no proxy, a disabled proxy, an unsupported target, or a non-critical persistence error. The package exposes sentinel errors and helper functions instead of requiring string parsing:

cfg, err := sysproxy.GetConfig()
switch {
case err == nil:
    fmt.Printf("current proxy: %+v\n", cfg)
case errors.Is(err, sysproxy.ErrProxyNotSet):
    fmt.Println("no proxy is configured")
case errors.Is(err, sysproxy.ErrProxyNotEnabled):
    fmt.Println("the manual proxy is not enabled")
case errors.Is(err, sysproxy.ErrUnsupportedPlatform):
    fmt.Println("this operating system is not supported")
default:
    return err
}

ErrToolMissing is returned when a required binary is absent — currently for the per-application Git and npm paths:

err := sysproxy.WriteAppConfig(sysproxy.AppGit, proxyURL)
if errors.Is(err, sysproxy.ErrToolMissing) {
    log.Println("git is not available in PATH")
}

On Linux, failing to update /etc/environment is wrapped as a non-critical error. A permission failure is additionally classified as requiring elevation:

if err := sysproxy.Set(proxyURL, sysproxy.ScopeGlobal); err != nil {
    switch {
    case sysproxy.RequiresElevation(err):
        log.Println("writing /etc/environment requires elevated permissions")
    case sysproxy.IsNonCritical(err):
        log.Printf("the /etc/environment step failed: %v", err)
    default:
        return err
    }
}

These helpers classify that persistence error. They do not independently prove that every preceding GNOME or KDE command succeeded, so verify the state with GetConfig when confirmation matters.

One broader point that applies across all platforms in v0.5.2: several platform setters intentionally ignore errors from individual native commands. A nil result therefore does not prove that every sub-step was accepted by the OS. Read state back when your application needs confirmation. On macOS specifically, Get and GetConfig inspect the first service returned by networksetup -listallnetworkservices, while setters iterate over all returned services.

Verify the endpoint before changing the system

Before your test harness reconfigures the OS, it is worth confirming the proxy is actually reachable. Check opens a TCP connection to the proxy endpoint:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

if err := sysproxy.Check(ctx, "http://proxy.example.com:8080"); err != nil {
    log.Fatalf("proxy is unreachable: %v", err)
}

This is a reachability check, not a full proxy handshake. It does not authenticate, perform an HTTP CONNECT, or complete a SOCKS handshake. A successful result means only that the host and port accepted a TCP connection.

Configure developer tools too

Routing OS traffic through a proxy does not automatically route git clone or pip install. The package ships explicit configuration writers for Git, curl, npm, pip, and wget:

proxyURL := "http://proxy.example.com:8080"

if err := sysproxy.WriteAppConfig(sysproxy.AppGit, proxyURL); err != nil {
    log.Fatal(err)
}
if err := sysproxy.WriteAppConfig(sysproxy.AppCurl, proxyURL); err != nil {
    log.Fatal(err)
}

// Later:
_ = sysproxy.ClearAppConfig(sysproxy.AppGit)
_ = sysproxy.ClearAppConfig(sysproxy.AppCurl)

These functions update application-specific configuration independently of the OS-level proxy functions.

Use it without writing Go

The repository includes a standalone CLI:

go install github.com/mar0ls/go-sysproxy/cmd/sysproxy@latest

sysproxy set http://127.0.0.1:8080
sysproxy set http://proxy.example.com:8080 --scope global
sysproxy get
sysproxy get --json
sysproxy check http://proxy.example.com:8080 --timeout 10s
sysproxy pac https://config.example.com/proxy.pac
sysproxy unset

One exit-code quirk to be aware of: get returns exit code 2 for any error, including the normal "proxy not set" case. Other command failures return 1. If you are scripting around this, check for both codes.

What happens under the hood

The public API stays the same across platforms; only the backend changes:

Platform	Native mechanism
macOS	`networksetup`
Linux / GNOME	`gsettings`
Linux / KDE	`kwriteconfig5` for writes; `kreadconfig5` or `kreadconfig6` for reads
Linux system environment	`Set`/`Unset` also edits `/etc/environment`
Windows	Current-user Internet Settings registry keys; `Set` calls `cmdkey` when URL credentials are present

All native commands go through exec.CommandContext with explicit argument lists, not shell construction. When the library creates Unix shell or application configuration files, it requests mode 0600; writing an existing file does not necessarily tighten its previous permissions.

Practical cautions before you ship

ScopeGlobal writes outside your process. Which applications read that store depends on the platform and the application.
/etc/environment on Linux may require root. Other native commands have their own permission models.
Some native setter subcommands are best-effort in v0.5.2. Verify important changes by reading state back.
Check proves TCP reachability only. It is not a proxy handshake.
Credentials in proxy URLs are handled differently by each backend. Avoid hard-coding them, and inspect where the selected OS or application persists them.
The package logger emits proxy URLs. If you install a logger with SetLogger, the audit messages from Set and WriteAppConfig include the supplied URL. Redact credentials in your adapter before forwarding to a shared system.
WithProxy with ScopeGlobal restores previous state; the other scopes do not. Shell and user-profile values are not preserved for ScopeShell or ScopeUser.
ScopeUser on Unix appends exports to .bashrc, .zshrc, .profile, and .bash_profile. Repeated calls can append duplicate lines. Inspect that behavior before using it as a configuration reconciler.

Final thoughts

go-sysproxy trades platform-specific scripts for a single Go API. In v0.5.2 that API covers contexts, sentinel errors, per-protocol settings, PAC support, TCP endpoint checks, a global-state restore helper, per-application configuration, and a CLI.

The scenario that opened this article — a test harness that applies a proxy, runs tests, and restores the previous state without touching the developer's setup — is four lines with WithProxy. The edge cases (multi-protocol corporate proxies, PAC mode, already-disabled proxies, missing tools) are handled by the same API with explicit error types rather than string matching.

Relevant source links for those who want to verify the implementation details:

The project is open source under the MIT license:

JA4 and JA4S fingerprints for QUIC traffic in Wireshark, with a Lua plugin

Marcin — Sat, 11 Jul 2026 20:29:49 +0000

More and more TLS traffic runs over QUIC (HTTP/3), and the classic JA3 fingerprint was never defined for it. Its successor, JA4, handles QUIC explicitly: the fingerprint gets a q prefix instead of t. Wireshark 4.2+ computes JA4 natively, but only the client side — there is no built-in JA4S (server fingerprint). I wrote a Lua plugin that fills that gap: ja4_quic.lua.

What Wireshark already gives you

Since 4.2, the TLS dissector exposes:

tls.handshake.ja3        tls.handshake.ja3s
tls.handshake.ja4        tls.handshake.ja4_r

Because the QUIC dissector hands the ClientHello to the TLS dissector, tls.handshake.ja4 also populates for QUIC Initial packets, with the correct q prefix:

$ tshark -r quic-tls-handshake.pcapng -T fields -e tls.handshake.ja4
q13d0310h3_55b375c5d22e_cd85d2d88918

What's missing from Wireshark's built-in TLS fields is JA4S. JA4 is available under the BSD 3-Clause License, while JA4S is part of the separately licensed JA4+ suite. FoxIO does provide its own JA4+ Wireshark plugin, but JA4S is not implemented by Wireshark's core TLS dissector.

The plugin

ja4_quic.lua is a postdissector that:

reads JA4 from the built-in field (no point recomputing it — GREASE handling and the QUIC detection are already done),
computes JA4S from the ServerHello,
tracks sessions by quic.connection.number (which survives QUIC connection migration) or tcp.stream,
adds filterable fields: ja4_quic.ja4, ja4_quic.ja4s, ja4_quic.ja4s_r, ja4_quic.sni, ja4_quic.alpn,
exports everything to CSV via Tools → Export JA4 Analysis.

JA4S in one minute

q 13 02 00 _ 1301 _ 234ea6891581
| |  |  |    |      |
| |  |  |    |      truncated SHA-256 of the extension list, in order
| |  |  |    cipher suite chosen by the server
| |  |  ALPN chosen ("00" if none visible)
| |  number of extensions
| TLS version (from supported_versions if present)
q = QUIC, t = TCP

One caveat worth knowing: in TLS 1.3 (and therefore in QUIC) the server sends its ALPN choice inside EncryptedExtensions, which is encrypted. Without TLS decryption secrets, a passive analyzer cannot recover that value, so the ALPN part is 00. This is a property of passive TLS 1.3 analysis rather than a limitation specific to the plugin.

Implementation notes

Wireshark doesn't expose a cryptographic hashing API to Lua, so the plugin carries its own SHA-256 implementation. It requires Wireshark 4.4 or newer, which ships with Lua 5.4 and its native bitwise operators. One important detail is that Lua integers are 64-bit, so every 32-bit rotation needs masking:

local function rotr32(x, n)
    return ((x >> n) | (x << (32 - n))) & 0xffffffff
end

The hash self-tests against a known vector at load time — a silently broken hash producing plausible-looking fingerprints would be worse than a crash.

Another Wireshark-specific gotcha: a postdissector runs again every time the GUI re-dissects a packet (clicking it in the packet list), so byte counters must only accumulate when pinfo.visited is false.

Verification

I compared the output against the FoxIO reference implementation (python/ja4.py from their repo) on their own sample pcaps. Every JA4S the reference emitted matches the plugin:

pcap	plugin	FoxIO reference
`latest.pcapng`	`t1206h2_c02f_3603f09c43ba`	`t1206h2_c02f_3603f09c43ba`
`latest.pcapng`	`t130300_1301_6bbbaf601ed8`	`t130300_1301_6bbbaf601ed8`
`chrome-cloudflare-quic` (TCP stream)	`t130200_1301_234ea6891581`	`t130200_1301_234ea6891581`

The reference script didn't emit a JA4S for the QUIC stream in that last capture, so the TCP row is the directly comparable one. On the QUIC side, JA4 matches Wireshark's built-in implementation, and the plugin's QUIC JA4S (q130200_1301_234ea6891581) differs from the verified TCP fingerprint only by the q prefix — expected, since it's the same server configuration.

Usage

Install Wireshark 4.4 or newer. The plugin uses Lua 5.4 syntax and will not load in Wireshark 4.2, even though that version already exposes the built-in JA4 fields.

Drop the file into your personal Lua plugins directory (About Wireshark → Folders → Personal Lua Plugins, e.g. ~/.local/lib/wireshark/plugins/), reload with Ctrl+Shift+L, and filter away:

ja4_quic.ja4s == "q130200_1301_234ea6891581"
ja4_quic.sni contains "example.com"

Licensing

JA4 (the client fingerprint) is available under the BSD 3-Clause License. JA4S and the rest of the JA4+ suite are specified by FoxIO and covered by the FoxIO License 1.1.

That license permits personal and academic use, as well as internal business use that does not directly monetize JA4+. Direct or indirect monetization — including incorporating JA4S into a paid product, hosted service, managed service, or other offering that provides value to paying customers — requires a separate license from FoxIO. The plugin follows the FoxIO specification and reference implementation and is published for non-commercial personal, academic and internal analysis. Review the full license before redistributing the plugin or using it in a commercial context.

A self-hosted web UI for managing and running Ansible - Playforge

Marcin — Tue, 07 Jul 2026 18:07:39 +0000

A self-hosted web UI for managing and running Ansible — a simpler, friendlier AWX
that runs from a single docker compose up, with no Postgres, Redis or Receptor. - Playforge

What makes it different is the AI layer that checks its own output. Most tools
either don't have AI or trust it blindly. Playforge generates playbooks from plain
language, then verifies them: it flags modules that don't exist, catches logic
mistakes a model misses (SSH/UFW lockout, destructive ops, malformed vars), and
grounds every answer in your real modules and files — fully offline.

Features

Projects & runs

Import an existing Ansible project from a local path, a .zip, or git clone (Gitea/GitHub) — junk like .venv/ and caches is filtered out automatically.
Every project is its own git repo with an auto-commit on each save: free undo, diff and history. Push/pull to a remote when you want.
Run playbooks (full or by tags) with live per-task output, a structured pass/fail summary, and a global, filterable run history.
Auto-detects playbooks/inventories/roles; works with both the scaffolded layout and flat repos (playbook + hosts.ini at the root).
Cron scheduler in-process (APScheduler — no extra worker), run templates, environments, ad-hoc commands.

Secrets

Credentials (SSH keys, SSH passwords, vault/become passwords, WireGuard) encrypted at rest with Fernet.
Ansible Vault for in-repo secrets — encrypt/decrypt/view from the UI.

Editor & dependencies

Monaco editor with inline ansible-lint, per-file commit history (View / Restore past versions), structured inventory editing (INI + YAML).
Playbook builder (simple → advanced: handlers, loops, serial, become per task).
Ansible Galaxy: install/remove roles & collections by name or from requirements.yml.

Operations

Credential test — probe an SSH key, SSH password, or sudo password against an inventory before running a 30-task playbook; per-host ✓/✗ result.
Ad-hoc command builder — any module + args + host pattern in one form (not just "ping all").
--limit quick-pick — click groups/hosts from the inventory to build the Ansible :-separated limit string.
Run artifacts — files a run wrote into the repo are committed automatically; the run-detail page previews them inline or opens them in the editor.
Per-schedule timezone — cron expressions interpret in any IANA timezone (Europe/Warsaw, America/New_York, …); next-fire times honour DST.

✨ AI assistant (the part that's actually unique)

Chat on every page (slide-out dock) and a full page — one shared conversation, live-synced and remembered across refreshes. Replies stream in token-by-token.
Agent mode: a tool-using agent that actually works on a project — it inspects files, writes/edits/moves them, installs collections, and can dry-run (--check) or run a playbook, then read the failures and fix them. It uses the self-checking layers below (it won't finish on a hallucinated module), every change is a separate git commit you can revert, and each capability is opt-in (read-only → "allow changes" → "allow delete / web").
NL → playbook: describe what you want, get a reviewable spec + YAML.
Remediation loop: after a failure, get a concrete fix and re-run only the failed hosts — or one-click Fix with agent to have the agent read the run, patch the playbook, and preview it.
Pre-run preview: a --check dry-run narrated in plain language ("what will change, where").
Auto-runbook: living Markdown docs generated from your playbooks.
Self-checking layers behind all of it:
- Anti-hallucination — module names validated against ansible-doc (ansible.builtin.ufw → flagged as fake; community.general.ufw → "install the collection", not "doesn't exist").
- Rule engine (neuro-symbolic) — catches lockout, destructive ops, contradictions, handler misuse, malformed structure, even inside roles.
- RAG / BM25 — grounds answers in the modules actually installed and in your project's real file contents. Works offline; optional web-fetch from docs.ansible.com when you allow it.

Pluggable model backends: Anthropic, OpenAI (or any OpenAI-compatible endpoint),
or a local Ollama server.

Screenshots

Quick start

git clone https://github.com/mar0ls/playforge.git
cd playforge
cp .env.example .env   # optional — for a password, AI keys, etc.
docker compose up --build -d   # → http://127.0.0.1:8765

The .env step is optional: with no .env the app runs single-user/local with no
AI. Configure the AI helper under Settings → AI helper at runtime, or set
OLLAMA_URL / ANTHROPIC_API_KEY / OPENAI_API_KEY in .env. State (projects,
git repos, SQLite) lives under ./data on the host and survives rebuilds.

Optional

Password protection: set ANSIBLE_GUI_PASSWORD to require login (signed session cookie). Unset = single-user local, no login.
Import your projects: bind-mount their directories read-only (see the commented /import/* examples in docker-compose.yml).
Naming note: the image and container are playforge; environment variables keep the ANSIBLE_GUI_* prefix for backward compatibility.

Try the self-checking loop

See it end to end without a remote host:

scripts/demo.sh   # creates a project + a deliberately failing run on localhost

It prints a run URL — open it and click Fix with agent: the agent reads the
failure, fixes the playbook (a typo'd module), and previews it. Then Re-run to
confirm. (To record a GIF, screen-capture the browser during that step.)

Development

make build      # build the image
make test       # run the full suite inside the image (git + ansible available)
make up / down  # start / stop

For live code reload while developing, layer the dev override (bind-mounts
backend/app and runs uvicorn with --reload):

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

The container exposes GET /health (DB ping included). The base compose wires
a Docker healthcheck against it, so docker ps shows (healthy) once the
service is up.

Lab regression (one command)

Run a full API-level regression for a dockerized VM lab (preflight + multiple
playbook runs + JSON report suitable for CI):

PROJECT_ID=<your_project_id> make lab-regression

Optional knobs:

PROJECT_ID=<id> \
BASE_URL=http://127.0.0.1:8765 \
INVENTORY_PATH=inventories/lab.ini \
HOST_PATTERN=all \
CHECK_PREFLIGHT=true \
INCLUDE_TARGETS_PREFLIGHT=true \
REQUEST_TIMEOUT_SEC=600 \
PLAYBOOKS_CSV=playbooks/lab_ping.yml,playbooks/lab_file.yml,playbooks/lab_apt.yml \
EXTRA_VARS_JSON='{"some_var":"value"}' \
make lab-regression

The command exits non-zero when preflight fails or any run is not ok/
successful.

The test suite (370+ cases) runs in CI on every push and PR — see
.github/workflows/ci.yml.

Design notes

Air-gap friendly: core UI JS libraries are vendored locally and AI can run against a local Ollama. By default, online docs lookup is off. Note: the Monaco editor assets are loaded from jsDelivr unless you vendor Monaco yourself.
No heavy infra: SQLite (WAL mode), in-process scheduler, direct runner. One container.
Third-party components are listed in THIRD_PARTY_LICENSES.md.

License

Copyright (C) 2026 mar0ls. Playforge is licensed under the GNU General Public
License v3.0 — see LICENSE. GPL-3.0 keeps the project compatible with
its core dependencies (ansible-core, ansible-runner, ansible-lint), which are
GPL-3.0 themselves. Forks and redistributed versions must stay open-source under
the same license.

Building agentless Linux threat detection in Go — no agents, no kernel modules, just SSH

Marcin — Fri, 03 Jul 2026 10:27:49 +0000

Most host-based detection tools require something running on every host: an agent, a kernel module, an eBPF program loaded at boot. That's fine when you control the fleet. It's less fine when you're dealing with a mix of distros, customer VMs, legacy systems where "please install our agent" gets stuck in a change window for six weeks.

I wanted something that works over SSH on a host you've never touched before — no install, no persistent process, no kernel dependency. Run a scan, get findings, nothing running between scans.

That's bladedr. This post explains how it works.

How the probe works

The core idea: SSH to the target, stage a static binary, run it, collect results.

The binary (bladedr-probe) is a single static Go executable compiled with CGO_ENABLED=0. It runs on the target for a few seconds, reads from /proc, /sys, /etc and a handful of other paths, builds a JSON snapshot of the host state, evaluates detection rules against it, and returns the findings on stdout. Nothing stays resident.

The snapshot covers:

running processes (cmdline, environ, exe, cwd, parent chain, deleted/memfd-backed executables)
listening sockets and raw (AF_PACKET) socket holders
kernel modules, /proc/kallsyms, dmesg ring buffer
persistence: cron, systemd units, authorized_keys, ld.so.preload, PAM modules, XDG autostart, binfmt_misc, udev rules, Python .pth files
accounts (uid/gid, shell, groups)
suspicious files: world-writable sensitive paths, SUID/SGID in unexpected places, deleted-but-running binaries, memfd mappings
kernel parameters (sysctl), SELinux state, immutable files

The probe is read-only. It doesn't start a daemon and it doesn't modify host state. The one thing it writes is itself: the binary is content-addressed (sha256) and cached at /tmp/.bladedr/probe-<hash>, so repeated scheduled scans skip the multi-MB re-upload. The small per-scan rule bundle is written next to it and deleted when the scan finishes. So there's no agent, no service, no process running between scans — just a cached binary sitting idle until the next SSH session invokes it. If you want it gone, it's one rm -rf /tmp/.bladedr.

Rules: YAML + CEL, not code

Detection logic is data, not compiled code. A rule looks like this (this one is a real builtin — global-ld-preload):

id: global-ld-preload
title: "LD_PRELOAD/LD_AUDIT / writable LD_LIBRARY_PATH in a global environment file"
category: evasion
severity: critical
score: 90
mitre: ["T1574.006"]
foreach: env_preload
when: 'item.suspicious_lines.size() > 0'
evidence:
  path: item.path
  lines: item.suspicious_lines
dedup: ["item.path"]

foreach walks a collection from the snapshot. when is a CEL expression evaluated against each item. CEL is a safe, deterministic expression language — no arbitrary code execution, fast evaluation, easy to audit. (Rules without a collection just run one when against the whole snapshot — e.g. the ld-so-preload-rootkit rule that fires on any entry in /etc/ld.so.preload.)

Rules ship embedded in the binary (internal/rules/builtin/), but the server merges three layers: builtin → filesystem dir (BLADEDR_RULES_DIR) → database. A later rule with the same id overrides the earlier one, so you can patch a builtin without recompiling, or disable it with enabled: false.

# live rule injection via API, active on the next scan
curl -X POST :8080/api/v1/rules --data-binary '
id: watch-loader
title: "Process named loader"
category: process
severity: medium
foreach: processes
when: item.comm == "loader"
evidence: { pid: item.pid, comm: item.comm }'

Currently 87 builtin rules covering MITRE ATT&CK techniques: rootkits, persistence, privilege escalation, evasion, webshells, supply-chain tampering, eBPF backdoors, and more.

The server

bladedr-server handles inventory, scheduling, the API, and the web console. It runs anywhere — Linux, macOS, Docker. Scan targets are always Linux.

Storage is in-memory by default (good for dev and demos), or Postgres with pg_search (BM25 full-text search over findings, useful when you have a few thousand observations and want to curl ':8080/api/v1/observations?q=rootkit').

The server keeps a per-host baseline. First scan establishes it. Later scans diff against it and raise baseline-new-* observations for anything new: a new UID-0 account, a new listening port, a new authorized key. You don't have to define what "normal" looks like — it learns from the first clean scan.

Fleet-rarity works similarly: if a kernel module or a cron entry appears on one host out of fifty, that's a low-severity lead regardless of whether any specific rule fires. Rarity is scoped to a host cohort (same OS), so a lone box doesn't generate rarity noise against unrelated hosts.

ML risk scoring — what it does and what it doesn't

With enough hosts, you end up with a lot of medium-severity findings. Some are real, most are noise. The risk model re-ranks open findings by how likely you are to triage them as real.

It's a multinomial Naive Bayes classifier (Laplace-smoothed) trained on your own triage decisions: acknowledged = real finding, false_positive = noise. It uses structural features only:

rule:global-ld-preload
cat:evasion
sev:critical
src:agentless_probe
tech:T1574.006
tac:T1574
path:etc

No attacker-controlled strings, no process names, no paths. It learns that certain rule/category/severity/technique combinations correlate with real compromises on your fleet, not on someone else's.

The model is honest about its own reliability. GET /api/v1/risk/stats runs leave-one-out cross-validation and reports whether the labelled set is big enough, balanced enough, and separable enough to trust:

{
  "trustworthy": true,
  "labeled": 211,
  "positives": 162,
  "negatives": 49,
  "cv_accuracy": 0.88,
  "base_rate": 0.77,
  "reason": "enough balanced, separable data to prioritise findings"
}

Until both classes exist (you need at least one acknowledged and one false_positive triage), scoring falls back to the rule's static score. A clean fleet produces no positives to label, so there's an attack-emulation range (poligon/) that plants known technique artifacts in a container, scans them, and writes labelled training data to dataset.jsonl.

It ranks. It does not detect.

eBPF tier (Phase 2)

Agentless scanning sees the artifact at rest — a file, a config entry, an account. It misses runtime-only techniques: fileless execution, a reverse shell that runs and exits, a container escape that leaves no trace.

The eBPF tier fills that gap. bladedr-sensor wraps Tetragon: it loads TracingPolicies (kprobes/tracepoints), consumes Tetragon's JSON event stream, maps each hit to an observation, and posts them to the server. Same observations table, same triage flow, same risk model — just source=ebpf_sensor instead of source=agentless_probe.

Tetragon runs as a privileged container. The sensor deploys over SSH and runs as a systemd unit. A host is either scan_only or scan_plus_sensor.

Running it

git clone https://github.com/mar0ls/bladedr
cd bladedr
make build               # server + probe for your platform
make build-probe-linux   # cross-compile static probe for Linux targets
make demo                # scan a bundled malicious snapshot, no Linux host needed

For SSH scanning against a real host:

# start server with Postgres
docker compose up -d
./bin/bladedr-server

# add a host, store credentials, scan
curl -X POST :8080/api/v1/hosts \
  -d '{"hostname":"web-01","primary_ip":"10.0.0.5","arch":"amd64"}'
curl -X POST :8080/api/v1/credentials \
  -d '{"username":"root","auth_type":"ssh_password","secret":"…"}'
curl -X POST :8080/api/v1/hosts/<id>/scans

bladedr is at v0.1.0 — the agentless tier is stable, the eBPF sensor works but Phase 2 rules are still thin. If you run it against a compromised or test host, I'd be curious what fires and what doesn't.

Rule contributions and issue reports welcome.

GPL-3. Code at [github.com/mar0ls/bladedr]