Lyrebird

A controlled internet for detonating samples

When you detonate malware in an isolated sandbox, it tries to reach the internet — to resolve a domain, beacon home, pull a payload, exfiltrate. Cut the network and it goes quiet, and you learn nothing. Lyrebird answers instead.

It stands up convincing fakes of the services malware reaches for — HTTP, DNS, SMTP, IRC, and more — so the sample behaves as if it were online while every byte stays inside the lab. Each interaction is recorded as one line of structured JSON, every uploaded payload is captured and hashed, and the whole session becomes evidence you can replay.

It's a spiritual successor to INetSim, whose last release shipped in 2020. Lyrebird keeps the proven model and rebuilds it async-first in Python, with one decisive difference: detection telemetry is a first-class output, not an afterthought.

Technique in, detection out

The core idea is a loop. A service emulates something malware does, tags the telemetry that matters, and a paired detection keys off that exact tag. The signal and the rule that catches it never drift apart because they're versioned together.

Because the detection is written against the same JSONL schema the emulator emits, you can develop and regression-test rules without ever touching live malware infrastructure — the captured session is a fixture.

Sixteen services, each a specimen

Lyrebird matches and extends INetSim's coverage. Every service answers, captures, and emits — and each is enabled or disabled independently in config.

One line of JSON per interaction

Everything keys off this schema — the log files, SIEM ingestion, the optional analysis layer, and every Sigma rule. It's the contract; change it deliberately.

// labdata/events/<session>.jsonl — one object per line
{
  "schema": "1.0",
  "ts": "2026-06-29T12:00:00.000+00:00",
  "session": "20260629T120000-a1b2c3",
  "event_id": "f3a9…",
  "service": "dns",        // http | dns | smtp | irc | …
  "transport": "udp",      // tcp | udp
  "src_ip": "10.13.37.66",
  "src_port": 51000,
  "dst_port": 53,
  "event_type": "request", // connection | request | auth | capture
  "summary": "A evil.example",
  "request":  { "qname": "evil.example.", "qtype": "A" },
  "response": { "rcode": 0, "answer": "10.13.37.1" },
  "artifacts": [],          // captured payloads, hashed + stored
  "tags": ["long-label"]   // what the detections select on
}

Captured payloads — uploads, mail bodies, raw socket data — are written to labdata/artifacts/<service>/, SHA-256 hashed, and referenced from the event's artifacts array. The tags field is the hinge: it's where a service flags behaviour, and where every rule below looks.

Every technique, its paired rule

A set of single-event Sigma rules and a correlation rule ship in detections/sigma/, each selecting on a tag the emulator emits. Levels are shipped defaults — tune to your environment. The full, always-current list is generated in REFERENCE.md.

For the cases a single event can't show

Timing and content evasions aren't single-event signatures. Three analytics run over a captured session and report the fingerprints those techniques leave behind — detection only; none generates traffic.

# defensive pair to beacon-jitter / rotation
python -m lyrebird.beacons \
  --session labdata/events/<id>.jsonl

# defensive pair to mimicry / encryption
python -m lyrebird.mimicry \
  --session labdata/events/<id>.jsonl \
  --data-dir labdata

# defensive pair to DNS exfil / tunneling
python -m lyrebird.dns_tunnel \
  --session labdata/events/<id>.jsonl

Boot a lab in one command

Run it directly, or containerized on an internal network with no outbound route.

From PyPI

pip install lyrebird-emulator
lyrebird

From source

pip install -r requirements.txt
python -m lyrebird --config config/lyrebird.yaml

Containerized — recommended

# compose network is `internal: true` — no egress by default
cd docker && docker compose up --build

Point your analysis VM's default gateway and DNS at the Lyrebird host, detonate the sample, and watch the events stream in. Toggle services at launch without editing config:

python -m lyrebird --disable smtp,ntp
python -m lyrebird --enable http,dns --no-banner

One readable YAML, sane defaults

Any omitted value falls back to a built-in default, so the file can be as small as you like — even empty gives a working lab. Responses are customizable per service without touching code.

bind_address: "0.0.0.0"
data_dir: "./labdata"
echo: true            # mirror events to stdout live

tls:
  enabled: true        # auto-generate a lab CA + leaf certs

services:
  http:
    enabled: true
    port: 80
    responses:           # first match wins → fakefile → model → default
      http:
        - path: "/gate.php"
          method: "POST"
          body: '{"status":"ok","task":"none"}'
  dns:
    enabled: true
    default_a: "10.13.37.1"   # sinkhole for unmatched A queries
    responses:
      dns:
        - qname: "*.evil-c2.com"
          answer: "10.13.37.66"     # point a family at one sink host

Response resolution is operator rule → fakefile → model responder (if enabled) → built-in default, and the chosen source is recorded on every event. Fakefile serving is path-traversal protected.

Optional analysis, never required

A vendor-agnostic model layer can triage a captured session into a verdict plus candidate Sigma ideas. It's optional and air-gap-friendly — selecting local keeps all data on-host.

python -m lyrebird.analyze \
  --session labdata/events/<id>.jsonl --provider local

Stay on the defensive side of the line

Lyrebird is a defensive tool, and contributions keep it there. The emulator responds to malware; it never becomes the malware.

The bar for a PR: tests green on Python 3.10–3.12, Sigma lint passing if you touched detections, new behaviour shipping with its paired detection, and an SPDX header on every file. If a change would make Lyrebird useful for attacking rather than observing, it's out of scope.

python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt pytest
PYTHONPATH=src python -m pytest tests/ -q      # all green
PYTHONPATH=src python scripts/lint_sigma.py    # detection lint