Detection You Can Read

Modern API security tools increasingly lean on behavioral models and confidence scores to flag suspicious activity. But when an alert arrives at 3 AM, the responder needs more than a probability — they need an explanation. This is the case for runtime detection an engineer can read, believe, and act on without reverse-engineering the tool that sent it.

There’s a moment in every incident that the dashboards never show you.

It’s 3:14 AM. Something fired. You’re looking at the alert, and before you do anything else, you have to answer one question for yourself: do I believe this?

Not “is it severe.” Not “what’s the runbook.” Just — is this real, or is it the thing that’s been crying wolf for the past three weeks. Everything downstream depends on that answer. Whether you wake up the on-call for the payments service. Whether you start a war room or go back to sleep. Whether, six hours from now, anyone trusts the next alert this system sends.

And here’s the problem with most API security tooling: at exactly that moment, it gives you the least to work with.

A score is not an explanation

The dominant model in API security right now is behavioral baselining. The tool watches your traffic, builds a model of “normal,” and scores deviations from it. When the score crosses some internal threshold, you get an alert. It usually looks something like:

Anomaly detected — endpoint /v2/accounts — confidence 0.87

Read that again at 3 AM with a pager going off.

What is 0.87? Is 0.87 bad? It’s higher than 0.5, so presumably yes. But you shipped a marketing campaign yesterday and traffic is up 4x — is the model counting that as anomalous? You genuinely cannot tell. The number is the output of a model you can’t inspect, trained on a baseline you didn’t define, weighting features you’ve never seen.

So you do the only thing you can do. You either trust it blindly, or you go pull the raw logs and reconstruct what actually happened from scratch — at which point the detection tool didn’t save you any work, it just added a step.

A confidence score asks for your trust without earning it. And trust that can’t be inspected isn’t trust. It’s superstition with a UI.

The question underneath the question

Step back from “did it detect the attack” and ask something narrower: can the person responding understand why it fired, and disagree if they need to?

That second clause matters more than the first. Detection that can’t be argued with can’t be tuned. If an engineer can’t see the logic, they can’t tell the difference between a false positive and a real one — they can only observe that the tool was wrong again and slowly stop reading its alerts. Many black-box detectors end up in muted Slack channels — not because they’re incapable of finding attacks, but because responders lose confidence in alerts they can’t explain. Nobody can fix what nobody can see.

Readable detection inverts that. The rule is something a human wrote, with a threshold a human chose, firing on signals a human can name. When it’s wrong, you can see why it was wrong, and move the threshold. When it’s right, you already understand the attack by the time you’ve finished reading the alert.

What a readable alert actually contains

Take a credential-stuffing attempt against a login endpoint. A baseline model gives you a score. A readable detector starts from a rule you can actually read:

Detector: Credential Stuffing
WHEN  failed login attempts  > 40 / minute  (per source)
AND   success rate           < 5%
AND   distinct usernames     > 100
THEN  raise alert  (severity: high, ATT&CK: T1110)

There’s no mystery in that. You can look at it, understand it, and disagree with it. If it’s too sensitive for your traffic, you can see exactly which number to move. When it fires, it gives you the case:

• The signals that fired: 1,400 distinct usernames against /auth/login from 12 IPs in one Autonomous System Number (ASN), 94% failure rate, over 6 minutes.
• The threshold that tripped: failed-auth velocity per source crossed the limit you set — and you can see what that limit is.
• The blast radius: which accounts saw a successful login after appearing in the failure set. That’s the part that turns “noise” into “incident.”
• The mapping: ATT&CK T1110. So you know the shape of what you’re looking at without having to name it yourself.
• A suggested response: rate-limit the ASN, force re-auth on the affected accounts.

Notice what’s deliberately not there: a confidence score. Not because confidence wouldn’t be reassuring, but because the moment you print “0.91” next to this, you’ve told the responder there’s a model making a probabilistic call they can’t audit — and you’ve put them right back at the 3 AM trust problem. The signals and the threshold are the confidence. They’re just legible.

And the same principle holds across the rest of the surface. Whether you’re detecting SQL injection attempts, endpoint enumeration, sensitive-data exposure, API key abuse, geographic anomalies, or a collection gap where telemetry simply goes quiet — the engineer should be able to read why the detector fired. The attack changes; the standard doesn’t.

The difference isn’t accuracy. A good baseline model and a good readable rule might fire on exactly the same traffic. The difference is what happens in the ninety seconds after they fire. One hands you a number to trust. The other hands you an argument you can check.

”But rules don’t learn”

The usual objection: static rules go stale, baselines adapt. Real traffic drifts, and a threshold you set in March is wrong by September.

That’s a fair critique of frozen rules. It is not an argument for hiding the rule.

This isn’t an argument against machine learning. It’s an argument that the output of machine learning should stay inspectable by the engineer responsible for responding. Learning and readability aren’t opposites. You can absolutely let observed traffic inform where a threshold sits — let the system propose that failed-auth velocity for this endpoint should be 40/minute, not 25, because that’s what six weeks of real behavior says. What you don’t do is let the learning become the detector. The adaptation tunes a number you can still see. The rule still reads in plain language. An engineer can still look at it, understand it, and override it.

The model informs the threshold. It doesn’t replace the rule, and it never makes the call in the dark. That’s the whole line, and it’s a line worth holding: adaptation you can read is an upgrade. Adaptation you can’t is just a black box with a learning rate.

Readable doesn’t mean perfect

None of this guarantees coverage. A readable detector can miss an attack, same as any other — a novel technique, a threshold set a little too loose, a signal nobody thought to watch. Explainability isn’t a claim of perfect recall.

The advantage shows up after the miss. When a readable rule fires incorrectly, or fails to fire at all, you have something concrete to fix: a named signal, a visible threshold, a piece of logic you can adjust and reason about. With an opaque model, a miss leaves you nothing to grab — you can’t tune what you can’t see, so you’re left retraining and hoping. Readable detection doesn’t promise you’ll never be wrong. It promises that when you are, you can do something about it.

The standard

Here’s the test I’d put on any runtime detection you’re evaluating, including ours:

Wake someone up with one of its alerts. Don’t explain it. Watch whether they can tell you what happened and whether they believe it — from the alert alone.

If they can, the tool is doing its job: it’s not just detecting, it’s transferring understanding to the one person who has to act on it. If they can’t — if the honest answer is “I’d have to dig into the logs to know” — then the detection didn’t save the work. It just relocated it to the worst possible hour.

Detection isn’t the hard part anymore. Most teams detect plenty. The hard part is producing one alert, about one real problem, that the engineer on call can read, believe, and act on without having to reverse-engineer the tool that sent it.

This is the principle we build APIGuard around: runtime detection should produce explanations before probabilities. Whether a threshold is hand-written, tuned from production traffic, or informed by historical behavior, the reasoning behind an alert should stay visible to the person who has to respond to it. The engineer shouldn’t have to reverse-engineer the detector before they can work the incident.

What does the last alert that woke you up tell you — and would you have trusted it without pulling the logs yourself?