What does an OWASP ZAP alert's alertRef identify, and what does Alert.setAlertRef refuse?

middlenice to knowfreq 30%

answer

identifies a kind, not an instance
one rule can own several
it must begin with its plugin id
empty is legal for a manual alert

basics

~20 s

The reference names the kind of alert, not the rule and not the occurrence, so one rule can have several. Setting one throws unless the string starts with the raising rule's plugin id — a check that is skipped while the reference is empty.

solid answer

~40 s

alertRef identifies a kind of finding. One plugin id belongs to one rule, one rule may report several kinds, and each kind carries its own name, description and its own risk and confidence pair. Alert.setAlertRef throws on null, on an over-long value, and unless the string starts with the plugin id rendered as a decimal — a plain prefix test with no separator required. Creating an alert with a plugin id seeds the reference to that id, so a single-finding rule needs to do nothing. An empty reference is explicitly legal and is what the contract asks for on a manually raised alert.

`alertRef` identifies a **kind** of finding. One plugin id belongs to one rule, one rule may report several kinds, and each kind carries its own name, description and its own risk and confidence pair. `Alert.setAlertRef` throws on null, on an over-long value, and unless the string starts with the plugin id rendered as a decimal — a plain prefix test with no separator required. Creating an alert with a plugin id seeds the reference to that id, so a single-finding rule needs to do nothing. An empty reference is explicitly legal and is what the contract asks for on a manually raised alert.

code

java · 14 lines

java

// Alert.setAlertRef - the prefix guard, and the condition that lets an empty value past
public void setAlertRef(String alertRef) {
    if (alertRef == null) {
        throw new IllegalArgumentException("Alert reference must not be null");
    }
    if (alertRef.length() > 0) {            // an empty reference skips the guard entirely
        // ...length check...
        if (!alertRef.startsWith(Integer.toString(this.pluginId))) {
            throw new IllegalArgumentException(
                    "Alert reference " + alertRef + " must start with the plugin id " + this.pluginId);
        }
    }
    this.alertRef = alertRef;
}

go deeper

for a junior

Remember the three identities and their cardinalities: a plugin id per rule, one or more references per rule, and many stored alerts per reference. Confusing the first two is the usual slip.

for a middle

Explain the guard precisely: a plain prefix test against the plugin id as a decimal string, applied only while the reference is non-empty, with the dash-and-qualifier shape being convention rather than enforcement.

for a senior

Show that your rollups group by reference rather than rule id, and be able to say what an empty reference in machine-generated output implies about where that alert came from.

for a principal

The identity your reporting keys on is a long-lived choice. Keying on rule id is simpler and permanently merges unlike findings; keying on reference is stable and finer-grained, and changing your mind later invalidates every historical comparison.

What the reference identifies

An OWASP ZAP alert carries an alertRef string beside its two scores, and it names the kind of alert, not the occurrence and not the rule. The distinction matters because all three are different cardinalities:

the plugin id identifies the scan rule — one per rule;
the alert reference identifies one of the kinds of finding that rule can report — one or more per rule;
the alert id identifies a stored occurrence — many per reference.

A rule that detects three genuinely different problems reports three references, and each one carries its own name, description and its own pair of risk and confidence values. That is why summarising a scan by plugin id flattens unlike findings together, and summarising by reference does not.

The one guard on the field, and what it actually checks

Alert.setAlertRef is unusually strict for this object. It is the only setter on the alert that checks a value against another field on the same object, and the contrast with its neighbours is sharp: setRisk and setConfidence are bare assignments that validate nothing at all, and the two range-checking helpers that exist beside them are called from nowhere in either main repository. The identity field is guarded; the score fields are not. setAlertRef throws on a null reference, throws on an over-long one, and then:

if (!alertRef.startsWith(Integer.toString(this.pluginId))) {
    throw new IllegalArgumentException(
            "Alert reference " + alertRef + " must start with the plugin id " + this.pluginId);
}

Three things are worth reading carefully in that guard.

It is a plain string prefix test. No separator is required and no structure is parsed. The convention every shipped rule follows is the plugin id, a dash, then a qualifier — but the convention is the rules' discipline, not the guard's.

It only runs on a non-empty reference. The whole block sits inside a length check, so an empty string passes straight through. That is deliberate and documented: the field's own contract says that for manually raised alerts the reference should be an empty string. So "a reference must start with the plugin id" is true of every reference a rule sets and not true of the field in general — an alert with no reference at all is a legal, ordinary alert.

The default comes from the constructor, conditionally. Creating an alert with a plugin id seeds the reference to that id rendered as a decimal string, so a single-finding rule needs to do nothing and its reference equals its id. But the seeding is guarded on the plugin id being a real one, and a hand-made alert has no rule behind it — so it keeps the empty reference the contract asks for.

	plugin id known	no plugin id (a manual alert)
reference after construction	the id as a decimal string	empty
prefix check on a later set	enforced	skipped while the value is empty
typical shape	`<id>` or `<id>-<qualifier>`	empty

Why the constraint exists at all

The reference is what lets anything downstream talk about this kind of finding without talking about a rule or an instance. Anchoring it to the plugin id makes it globally unique without a registry: two rules cannot collide, because the prefix is already unique, and a rule cannot accidentally claim a reference belonging to another rule, because the constructor refuses it. It also means a reference is self-describing — reading one tells you which rule produced it, which is exactly what a person reading a report needs when a reference they do not recognise appears.

What this means when you read scan output

Three things to carry into a pipeline:

Group by reference, not by rule. Two rows sharing a plugin id may be different problems at different severities. The reference is the stable identity of "this finding type".
An empty reference means nobody raised it as a rule. It is the fingerprint of a manually added alert, and it is worth noticing when one appears in machine-generated output.
A reference is not a severity and not a version. It encodes no band and no ordering. The qualifier after the dash is an arbitrary discriminator chosen by the rule author, so comparing two qualifiers tells you nothing about which finding is worse — the risk and confidence fields on the alert are the only things that do.

## What the reference identifies An OWASP ZAP alert carries an `alertRef` string beside its two scores, and it names the **kind of alert**, not the occurrence and not the rule. The distinction matters because all three are different cardinalities: - the **plugin id** identifies the scan rule — one per rule; - the **alert reference** identifies one of the kinds of finding that rule can report — one or more per rule; - the **alert id** identifies a stored occurrence — many per reference. A rule that detects three genuinely different problems reports three references, and each one carries its own name, description and its own pair of risk and confidence values. That is why summarising a scan by plugin id flattens unlike findings together, and summarising by reference does not. ## The one guard on the field, and what it actually checks `Alert.setAlertRef` is unusually strict for this object. It is the only setter on the alert that checks a value against **another field on the same object**, and the contrast with its neighbours is sharp: `setRisk` and `setConfidence` are bare assignments that validate nothing at all, and the two range-checking helpers that exist beside them are called from nowhere in either main repository. The identity field is guarded; the score fields are not. `setAlertRef` throws on a null reference, throws on an over-long one, and then: ``` if (!alertRef.startsWith(Integer.toString(this.pluginId))) { throw new IllegalArgumentException( "Alert reference " + alertRef + " must start with the plugin id " + this.pluginId); } ``` Three things are worth reading carefully in that guard. **It is a plain string prefix test.** No separator is required and no structure is parsed. The convention every shipped rule follows is the plugin id, a dash, then a qualifier — but the convention is the rules' discipline, not the guard's. **It only runs on a non-empty reference.** The whole block sits inside a length check, so an empty string passes straight through. That is deliberate and documented: the field's own contract says that for manually raised alerts the reference **should** be an empty string. So "a reference must start with the plugin id" is true of every reference a rule sets and not true of the field in general — an alert with no reference at all is a legal, ordinary alert. **The default comes from the constructor, conditionally.** Creating an alert with a plugin id seeds the reference to that id rendered as a decimal string, so a single-finding rule needs to do nothing and its reference equals its id. But the seeding is guarded on the plugin id being a real one, and a hand-made alert has no rule behind it — so it keeps the empty reference the contract asks for. | | plugin id known | no plugin id (a manual alert) | |---|---|---| | reference after construction | the id as a decimal string | empty | | prefix check on a later set | enforced | skipped while the value is empty | | typical shape | `<id>` or `<id>-<qualifier>` | empty | ## Why the constraint exists at all The reference is what lets anything downstream talk about *this kind of finding* without talking about a rule or an instance. Anchoring it to the plugin id makes it globally unique without a registry: two rules cannot collide, because the prefix is already unique, and a rule cannot accidentally claim a reference belonging to another rule, because the constructor refuses it. It also means a reference is self-describing — reading one tells you which rule produced it, which is exactly what a person reading a report needs when a reference they do not recognise appears. ## What this means when you read scan output Three things to carry into a pipeline: 1. **Group by reference, not by rule.** Two rows sharing a plugin id may be different problems at different severities. The reference is the stable identity of "this finding type". 2. **An empty reference means nobody raised it as a rule.** It is the fingerprint of a manually added alert, and it is worth noticing when one appears in machine-generated output. 3. **A reference is not a severity and not a version.** It encodes no band and no ordering. The qualifier after the dash is an arbitrary discriminator chosen by the rule author, so comparing two qualifiers tells you nothing about which finding is worse — the risk and confidence fields on the alert are the only things that do.

Is an empty `alertRef` valid?
Yes, and it is what the field's own contract prescribes for a manually raised alert. The prefix check sits inside a length test, so an empty string bypasses it. An alert built without a real plugin id also keeps an empty reference, because the constructor only seeds one when a plugin id is present.
Does the alert reference tell you anything about severity?
No. It encodes no band and implies no ordering — the qualifier after the dash is an arbitrary discriminator chosen by the rule author. Two references from one rule can sit at opposite ends of the risk scale, and only the risk and confidence fields on the alert say which is which.
Why anchor the reference to the plugin id rather than let rules name them freely?
It makes references globally unique with no central registry: the id prefix already distinguishes rules, so two rules cannot collide and one cannot claim another's reference. It also makes a reference self-describing — reading an unfamiliar one tells you which rule produced it.

saying these in an interview costs you the question

Says the reference identifies one occurrence of a finding
Thinks every rule has exactly one alert reference
Believes the reference encodes the risk band
Assumes a reference may be any string the rule chooses
Says an empty reference is rejected outright

What does an OWASP ZAP alert's alertRef identify, and what does Alert.setAlertRef refuse?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

What the reference identifies

The one guard on the field, and what it actually checks

Why the constraint exists at all

What this means when you read scan output

▾common follow-ups3 questions

▾red flags5 flags

What the reference identifies

The one guard on the field, and what it actually checks

Why the constraint exists at all

What this means when you read scan output

answer

go deeper