MCP Tools Security - NormB/sipnab GitHub Wiki
The security bundle answers who sent what: scanner and fraud findings, the
busiest sources, one endpoint's activity, registration problems, pass/fail
expectations, and fail2ban rules.
Load only these tools with --mcp-tools security, or combine bundles as
Choosing which tools load describes.
Every tool on this page follows the rules every tool
follows, and each section states only
what its tool does differently. The MCP tool reference lists
the other bundles and finds any tool by name.
| Tool | Parameters | Returns |
|---|---|---|
top_talkers |
by, limit?, filter?, named?, prefix_digits?
|
The busiest IPs, user agents or dialed prefixes, ranked, each share stated against the population behind it |
describe_endpoint |
ip?, user?, limit?
|
Everything one participant did: dialogs by method and state, INVITE outcomes, REGISTER state, banners, streams, findings |
diagnose_registration |
call_id |
Whether an endpoint registered, hit a rejection, is looping on auth, or got a short expiry |
evaluate_expectations |
rules?, rules_toml?, suppression_file?
|
A pass/fail verdict per rule plus an exit code for a build. A rule whose population is empty fails rather than passing quietly |
security_findings |
kinds?, since?, limit?
|
Recent scanner / fraud / digest / reg_flood findings, plus the detectors this server runs |
generate_fail2ban_rule |
finding_id |
A fail2ban filter and jail derived from ONE recorded finding, with that finding attached as the evidence |
Start here when you have a capture and no particular suspect. These answer "what is in it", "how much", and "is the server even seeing traffic".
Ranks the busiest participants: IPs, user agents, or dialed prefixes.
Use it to answer "who is busiest". aggregate_dialogs and group_dialogs
group DIALOGS, which have two ends. top_talkers counts PARTICIPANTS, so it
credits both ends of a dialog.
| Name | Type | Legal values | If omitted |
|---|---|---|---|
by |
string |
ip, ua or prefix. Anything else fails with invalid_params, reason: invalid_choice, and the legal set in valid_values. |
Required. |
limit? |
integer? | Bounded by --mcp-max-rows. |
The usual row default. |
filter? |
string? | Alias or DSL, the same vocabulary every other tool takes. | The whole store. |
named? |
string? | A [filters] name or alias, in place of filter, as list_dialogs takes it. |
filter decides. |
prefix_digits? |
integer? | How many leading digits make a prefix bucket. 0 fails with reason: invalid_value, param: prefix_digits. |
4. |
Returns:
| Field | Type | Description |
|---|---|---|
by |
string | Echo of the dimension ranked on, so an answer is self-describing. |
talkers |
object[] | Busiest first, bounded by limit. |
distinct_talkers |
usize | Talkers seen across the whole match, whether or not each got a row. |
total_matched |
usize | Dialogs the filter matched across the whole store. |
truncated |
bool |
true when distinct_talkers exceeds the rows returned. |
capture_identity |
object | Which capture answered — see capture_status. |
schema_version |
u32 |
1 for this shape. |
Each talkers row carries key (the address, banner or prefix), dialogs,
messages, invites, answered, failed, and share_pct. messages counts
what sipnab credits to the row: messages SENT for an ip, messages carrying
the banner for a ua, every message of the dialog for a prefix. answered
and failed are subsets of invites, so a dimension carrying no INVITE dialogs
reports zero for all three. share_pct is null, not 0, when nothing
matched.
The example runs against tests/pcap-samples/sipp-branch-scenario.pcapng,
whose 1334 REGISTER dialogs run between two addresses:
The shares can sum above 100%. One dialog counts for every talker
in it, so a two-ended call adds to two rows — here both ends took part in all
1334 dialogs and both read 100%. total_matched is the number that partitions:
compare a row's dialogs against it rather than against the other rows.
by: "prefix" is the exception and does partition, because sipnab credits one
bucket per dialog and a call has one dialed number.
sipnab orders rows by dialogs, then by messages, then by key, so the
order is the same on every run over one capture. key arrives fenced for
by: "ua" alone, because the sender wrote the banner. An address and a prefix
bucket are values sipnab derived, and come back verbatim.
ip reads senders off the MESSAGES, not off the dialog's opening addresses,
so the count includes a proxy that re-originates mid-dialog. ua reads User-Agent from requests and Server from
responses, both sender-written and therefore fenced. prefix strips a leading
+ before taking digits, so +15551234 and 15551234 are one destination
rather than two.
You know something is wrong but not which call. These cut a capture down to the dialogs worth reading: by symptom, by text, by time, or by relationship to a call you already have.
Everything the capture holds about one participant.
Use it when you start from a phone, a trunk or a subscriber rather than a Call-ID: give an address or a SIP user name, and it answers what that participant has been doing, from every dialog the store holds.
| Name | Type | Legal values | If omitted |
|---|---|---|---|
ip? |
string? | The endpoint's address, v4 or v6. Mutually exclusive with user. An unparseable value fails with a message such as ip 'bogus' is not an address: invalid IP address syntax. |
Give user instead. |
user? |
string? | The user part of a SIP URI — alice from sip:[email protected]. Mutually exclusive with ip. |
Give ip instead. |
limit? |
u32? | Bounds recent_dialogs, problem_call_ids and findings only. Ceiling is --mcp-max-rows (1000 by default), 0 means the default. |
50. |
Give exactly one selector. Passing both ip and user fails with
invalid_params and reason: conflicting_params:
{ "code": -32602,
"message": "give exactly one of ip or user, not both: the two select different sets, and whether you meant their intersection or their union changes the answer",
"data": { "reason": "conflicting_params" } }Passing neither fails with reason: missing_param. An ip that does not
parse fails with reason: invalid_value and param: ip.
The example runs against
tests/pcap-samples/sip-rtp-g711.pcap:
// describe_endpoint { "ip": "10.0.2.20", "limit": 1 }
{
"by_method": {
"INVITE": 2
},
"by_state": {
"Completed": 1,
"InCall": 1
},
"calls": {
"by_final_status": {
"200": 2
},
"failed": 0,
"failure_rate_pct": 0.0,
"invites": 2,
"with_final_status": 2
},
"capture_identity": {
"dialog_generation": 13,
"instance": "60d3618dfa9481ddb9840-2",
"node": "capture-01",
"stream_generation": 2
},
"dialogs": 2,
"endpoint": "10.0.2.20",
"endpoint_kind": "ip",
"findings": {
"armed_kinds": [],
"findings": [],
"note": "No detection rule is armed on this server, so no finding could have been recorded. An empty findings list here means nothing was watching, NOT that this endpoint was clean. Arm a detector with --kill-scanner, --fraud-detect, --digest-leak or --reg-flood and re-run the capture.",
"selectable": true,
"total_matched": 0
},
"messages_received": 5,
"messages_sent": 5,
"recent_dialogs": [
{
"call_id": "[email protected]",
"created_at": "2016-11-26T14:53:08.286194+00:00",
"duration_sec": 0.004,
"earliest_message_at": "2016-11-26T14:53:08.286194+00:00",
"final_status_code": 200,
"frame": "tests/pcap-samples/sip-rtp-g711.pcap#433@b034a3ca525e06ff",
"from_user": "⟦untrusted-capture-data⟧sipp⟦/untrusted-capture-data⟧",
"input_origin": "wire",
"latest_message_at": "2016-11-26T14:53:08.290927+00:00",
"method": "INVITE",
"msg_count": 4,
"state": "InCall",
"timing": {
"duration_ms": null,
"pdd_ms": null,
"retransmits": 0,
"setup_ms": 4
},
"to_user": "⟦untrusted-capture-data⟧test⟦/untrusted-capture-data⟧",
"updated_at": "2016-11-26T14:53:08.290927+00:00"
}
],
"registration": {
"applicable": false,
"auth_loops": 0,
"dialogs": 0,
"failed": 0,
"problem_call_ids": [],
"succeeded": 0
},
"schema_version": 1,
"source_exhausted": true,
"source_stopped_early": false,
"stack": {
"branch_cookie": "z9hG4bK",
"branch_shape": "other",
"callid_has_host": true,
"confidence": 0,
"mixed": false,
"requests_read": 4,
"tag_shape": "hex"
},
"streams": {
"codecs": [
"⟦untrusted-capture-data⟧PCMA⟦/untrusted-capture-data⟧",
"⟦untrusted-capture-data⟧PCMU⟦/untrusted-capture-data⟧"
],
"count": 2,
"lost_packets": 0,
"max_jitter_ms": 0.0061987502747274615,
"orphaned": 0,
"packets": 839
},
"truncated": true,
"user_agents": []
}A phone behind NAT puts its own private address in the Contact of a REGISTER.
The registrar must notice that the packet arrived from a public address the
header does not name, and route later requests to where it came from. When it
does not, every inbound call goes to an unroutable host and the phone never
rings.
Alert on is_finding, not on the observation. A private Contact from a
public source is common on working deployments. It is a fault only when later
requests went to the private host.
| Field | Type | Description |
|---|---|---|
observation.contact_host |
string? | The host the Contact named, as written. Absent for Contact: *, which RFC 3261 section 10.2.2 defines as every binding and which names no host |
observation.contact_host_private |
bool? | Whether that host is one the public internet does not route to. Absent when the Contact names a domain: a name resolves somewhere the capture cannot see, and judging it either way would be a guess |
observation.source_public |
bool | Whether the REGISTER arrived from a public address |
observation.rewrite_required |
bool | The two together — the shape that calls for a NAT rewrite |
verdict |
string |
rewritten, not-rewritten or no-later-requests
|
requests_to_contact |
usize | Later requests addressed to the private Contact host |
requests_to_source |
usize | Later requests addressed to where the REGISTER came from |
is_finding |
bool | The conjunction: the shape called for a rewrite and no rewrite happened. This is the field to alert on |
One request to the private host makes it a finding, even when most later requests went to the source address.
no-later-requests is not success. It means the capture ended before any
later request to this endpoint, so it cannot say whether the rewrite happened.
Capture longer, past the first inbound call.
sipnab matches later requests by the registered AoR, not the address. A
request sent to the private Contact carries no address of the endpoint, so
sipnab ties it to the endpoint by the user part in the request URI and To,
matched case-sensitively per
RFC 3261 section 19.1.4.
diagnose_registration reports the observation for a
single call. This tool reports the finding, because it needs the endpoint's
other dialogs.
A banner names a PRODUCT, and one product can ship more than one SIP stack,
each needing different configuration, NAT handling and re-INVITE handling.
Use stack to tell endpoints with the same User-Agent apart by the syntax
of the requests they send.
| Field | Type | Description |
|---|---|---|
branch_cookie |
string? | The Via branch's cookie: the mandatory z9hG4bK (RFC 3261 section 8.1.1.7) plus any vendor extension before the per-transaction part. Echoed from the wire, bounded to 32 characters |
branch_shape |
string? | What follows the cookie: uuid, as-hex, hex or other
|
tag_shape |
string? | The same vocabulary, for the From tag |
callid_has_host |
bool? | Whether the Call-ID carries an @host part |
inference |
string? | The library the observations point at — pjproject or chan_sip. Absent when they point nowhere |
confidence |
u8 | How many of the three observations agree with inference, out of three. 0 when sipnab inferred nothing |
requests_read |
usize | The denominator. A fingerprint from one request and one from four hundred are different claims |
mixed |
bool | True when this endpoint's own requests disagreed. A shared address, or a proxy relaying for others, carries both populations |
It names a library, never a product. z9hG4bKPj is pjproject's, and
pjproject ships inside Asterisk's res_pjsip, Grandstream UCM and FreePBX
alike, so the shape does not identify a vendor.
An inference needs two agreeing observations. The magic cookie is
mandatory for every compliant sender, and callid_has_host alone is common to
many stacks, so one agreeing observation infers nothing. An unrecognized stack
reports its shapes with no inference.
Read from requests only. A response echoes the request's branch, From tag
and Call-ID, so it describes the sender of the request, not the responder.
An endpoint that only answers reports requests_read: 0 and infers nothing.
limit bounds the page and never the counts. dialogs, by_method,
by_state, calls and streams describe every match, and only
recent_dialogs shortens, with truncated saying so. recent_dialogs runs
newest first. To page the whole history oldest first, use
list_dialogs.
An ip matches on MESSAGES, not on the dialog's opening addresses, so a
proxy re-originating mid-dialog, a re-INVITE from a second interface, and a BYE
from the far side all count toward the endpoint that sent them.
A user matches the From or To user part EXACTLY. RFC 3261
section 19.1.4 makes the user
part case-sensitive, so Alice and alice are two endpoints.
Three fields answer differently for a user:
| Field | For a user
|
Why |
|---|---|---|
messages_sent, messages_received
|
Always 0
|
A URI user part names a party, not a socket, so it does not say which party sent a given message. |
streams |
The streams linked to that user's dialogs | A user has no media identity of its own, so the Call-IDs are the only bridge. An ip matches the media 5-tuple directly and therefore sees orphans too. |
findings.selectable |
false, with a note
|
The alert engine files every finding against a source IP, so no key selects a user. Re-ask with the address. |
An empty findings.findings list has three readings. Tell them apart before
concluding anything:
-
selectable: false: no key selects findings for this endpoint (auser). Re-ask with the address. - An empty
armed_kinds: nothing was watching, and thenotesays so in the same wordssecurity_findingsuses. - Only with a detector armed does an empty list mean the endpoint tripped nothing.
failure_rate_pct is null, not 0.0, when no INVITE reached a final status.
registration.applicable: false means the endpoint sent no REGISTER, so the
four counts under it are zero for lack of input. sipnab counts registrations by
the REGISTER request, including one sent inside a dialog another method
opened. Pass the Call-IDs in problem_call_ids to
diagnose_registration.
user_agents attributes a banner to whoever wrote it: User-Agent off requests
the address SENT and Server off responses it sent, per RFC 3261
section 20.41 and
RFC 3261 section 20.35.
For a user, only User-Agent on requests whose From user matches counts.
Values arrive fenced, and so do the summaries in recent_dialogs.
You have a call-id. These explain what happened to that one call -- its signaling, its media, and the specific negotiations that tend to break.
"Is this phone online?" — a different question from "why did this call fail?".
Parameters: call_id (string, required) — a Call-ID the store holds. No
optional parameters. The call need not carry a REGISTER, and the answer says
so when it does not.
Read applicable first. It is false for a dialog carrying no REGISTER,
and the response then holds only call_id, reason, schema_version and
the source flags — no hints, no registration_failure:
// diagnose_registration { "call_id": "[email protected]" } — an INVITE dialog
{
"schema_version": 1,
"call_id": "[email protected]",
"applicable": false,
"reason": "this dialog carries no REGISTER request",
"capture_identity": { "node": "capture-01", "instance": "cc2cb18df0ea68adfb9c9-2",
"dialog_generation": 13, "stream_generation": 2 },
"source_exhausted": true,
"source_stopped_early": false
}When it does apply, registration_failure is null for a registration that
worked, and otherwise names the kind — rejected, shortened_expiry or an
auth loop reported through auth_loop. evidence lists the message indexes
behind the verdict, ready for get_message. The example runs
against
tests/pcap-samples/sip-auth-failure.pcapng:
// diagnose_registration { "call_id": "[email protected]" }
{
"schema_version": 1,
"call_id": "[email protected]",
"applicable": true,
"final_status_code": 403,
"auth_loop": null,
"registration_failure": {
"kind": "rejected",
"code": 403,
"evidence": [0, 3],
"requested_expiry_sec": null,
"granted_expiry_sec": null
},
"contact_rewrite": {
"contact_host": "203.0.113.1:42952",
"contact_host_private": false,
"source_public": true,
"rewrite_required": false
},
"hints": [
"Call failed: 403 Forbidden.",
"Registration rejected: 403 Forbidden. The endpoint answered an authentication challenge and the registrar refused the credentials it offered, so the fault is in the account, its password or its permission to register — none of which is a reachability problem."
],
"capture_identity": { "node": "capture-01", "instance": "cc2d618df0ea70d0788a2-2",
"dialog_generation": 8, "stream_generation": 0 },
"source_exhausted": true,
"source_stopped_early": false
}registration_failure.code is the status that decided the verdict.
A phone behind NAT registers its own private address, and the registrar must notice the packet came from a public address the header does not name and route later requests there instead. When it does not, every inbound call goes to an unroutable host and the phone never rings.
rewrite_required is contact_host_private && source_public. The sample
above reports false: a public Contact from a public source needs nothing
rewritten. false does not rule out other faults.
| Field | Type | Description |
|---|---|---|
contact_host |
string? | The host the Contact named, as written. Absent for Contact: *, which RFC 3261 section 10.2.2 defines as every binding and which names no host |
contact_host_private |
bool? | Whether that host is one the public internet does not route to. Absent when the Contact names a domain, which resolves somewhere the capture cannot see |
source_public |
bool | Whether the REGISTER arrived from a public address |
rewrite_required |
bool | The two together |
This block is an observation, not a finding. A private Contact from a
public source is common on working deployments. Whether it is a fault depends
on which address later requests used, which one dialog cannot show. To get the
finding, ask describe_endpoint with the endpoint's
address and read verdict and is_finding.
The block is absent when the dialog carries no REGISTER — the same
applicable: false case the top of this section describes.
Whether the traffic obeys the RFCs, and which clause it broke. These turn "the call failed" into "12.1.1 requires a Contact and there is none".
A pass/fail verdict on the loaded capture, and an exit code for a build. Fail a build on what a capture shows covers the suite file and the same check from the command line.
Use it to check a capture against written rules, such as "no 488
responses" or "MOS p10 at least 4.0". The rules can live in a checked-in
sipnab.expect.toml beside the SBC configuration, and an agent passes that
file's text in rules_toml.
| Name | Type | Legal values | If omitted |
|---|---|---|---|
rules? |
object[]? | The suite inline. Each rule is {metric, op, value} plus optional name, scope, min_sample and grounded_only. Mutually exclusive with rules_toml. |
Give rules_toml instead. |
rules_toml? |
string? | The verbatim text of a sipnab.expect.toml. Mutually exclusive with rules. |
Give rules instead. |
suppression_file? |
string? | A lint suppression file in --mcp-file-root, applied to the lint_errors rules. |
Discovers a .sipnablint beside the capture, exactly as lint_dialog does. |
Pass the file's text unchanged in rules_toml, so the tool judges the capture
against the same rules the file holds. Pass exactly one of rules and
rules_toml: both, or neither, fails with invalid_params.
One rule is a metric, a comparison, a threshold, and what it applies to:
| Field | Legal values |
|---|---|
metric |
count (dialogs matching the scope), asr (answered over seized, as a PERCENT from 0 to 100, the same unit group_dialogs reports), lint_errors (conformance findings at or above a severity floor), mos_p<N> (a MOS percentile, mos_p0 worst to mos_p100 best). |
op |
>=, >, <=, <, ==, !=
|
value |
The threshold, in the metric's own unit. |
scope |
filter:<alias-or-DSL> to narrow by dialog, or severity:<info|notice|warning|error> to set the floor a lint_errors rule counts from. Omitted means the whole capture. |
min_sample |
Observations below which the rule reports skipped rather than a verdict. |
grounded_only |
MOS metrics only. Defaults to true. |
The text in rules_toml holds the same fields as TOML, one [[rules]] table
per rule:
[[rules]]
name = "answer rate"
metric = "asr"
op = ">="
value = 10
[[rules]]
metric = "lint_errors"
op = "<="
value = 0
scope = "severity:error"The table name is rules, plural. Rules under another name, such as
[[rule]], or written at the top level of the text, are not read. The suite
is then empty, and the call fails with invalid_params (-32602) and this
message:
an expectation suite must contain at least one rule; an empty suite passes every capture and reports nothing
// evaluate_expectations { "rules": [
// { "name": "no codec rejections", "metric": "count", "op": "==", "value": 0,
// "scope": "filter:response_code == 488" },
// { "name": "audio floor", "metric": "mos_p10", "op": ">=", "value": 4.0 },
// { "name": "answer rate", "metric": "asr", "op": ">=", "value": 99, "min_sample": 50 } ] }
{
"schema_version": 2,
"verdict": "pass",
"exit_code": 0,
"rules_total": 3, "evaluated": 2, "passed": 2, "failed": 0, "skipped": 1,
"dialogs_in_capture": 2,
"streams_in_capture": 2,
"suppressions_applied": false,
"results": [
{ "index": 0, "name": "no codec rejections", "metric": "count",
"unit": "dialogs", "op": "==", "threshold": 0.0,
"scope": "filter:response_code == 488", "observed": 0.0, "sample": 2,
"verdict": "pass", "reason": "0 is == 0 over 2 dialog(s)" },
{ "index": 1, "name": "audio floor", "metric": "mos_p10",
"unit": "mos (1.0-5.0)", "op": ">=", "threshold": 4.0,
"observed": 4.358100156401542, "sample": 2, "ungrounded_excluded": 0,
"verdict": "pass", "reason": "4.3581 is >= 4 over 2 scored stream(s)" },
{ "index": 2, "name": "answer rate", "metric": "asr",
"unit": "percent", "op": ">=", "threshold": 99.0,
"observed": 100.0, "sample": 2, "min_sample": 50,
"verdict": "skipped",
"reason": "skipped: 2 seizure(s) is below the declared min_sample of 50" }
],
"capture_identity": { "node": "capture-01", "instance": "135ff718df00a2924a3f56-2",
"dialog_generation": 13, "stream_generation": 2 },
"source_exhausted": true,
"source_stopped_early": false
}That example runs against
tests/pcap-samples/sip-rtp-g711.pcap.
Read unit on every outcome. It names the scale the observed value and
the threshold are on: percent for asr (0 to 100, as
group_dialogs reports it), dialogs
for count, and the MOS range for a mos_p<N> metric. Write value on that
scale: 99, not 0.99, for a 99% answer rate.
An empty population FAILS, and the message says why. How the tool treats the three cases where a rule has too little to judge:
| Case | What this tool does |
|---|---|
| The rule's population is empty | The rule reports fail with reason beginning unevaluable:. A MOS threshold on a capture whose streams all use a codec with no published impairment value fails this way. |
The sample is below the rule's min_sample
|
The rule reports skipped, not a verdict. |
| Every rule in the suite skipped | The suite reports not_evaluated with exit code 2, distinct from a pass. |
To accept an empty population, declare min_sample of 1 or more on the rule.
min_sample: 0 declares no floor, so the empty case still fails.
// evaluate_expectations { "rules": [{ "metric": "asr", "op": ">=", "value": 95 }] }
// on tests/pcap-samples/sip-register.pcap, one REGISTER dialog and no call attempt:
{
"capture_identity": {
"dialog_generation": 2,
"instance": "6263318dfa94d596b0175-2",
"node": "capture-01",
"stream_generation": 0
},
"dialogs_in_capture": 1,
"evaluated": 1,
"exit_code": 3,
"failed": 1,
"passed": 0,
"results": [
{
"index": 0,
"metric": "asr",
"observed": null,
"op": ">=",
"reason": "unevaluable: no seizure was in scope, so 'asr >= 95' rests on nothing. Declare a min_sample of 1 or more to accept an empty population in writing; a gate does not pass on data it never judged",
"sample": 0,
"threshold": 95.0,
"unit": "percent",
"verdict": "fail"
}
],
"rules_total": 1,
"schema_version": 2,
"skipped": 0,
"source_exhausted": true,
"source_stopped_early": false,
"streams_in_capture": 0,
"suppressions_applied": false,
"verdict": "fail"
}The verdict tests the size of the SAMPLE, not whether a value came back, so
count == 0 fails on a capture holding no dialogs at all.
exit_code is the exit status --expect gives the same suite: 0 every rule
that ran passed, 3 at least one failed, 2 nothing ran. Reports before
schema_version 2 carried 1 for a failed suite. It moved to 3, sipnab's
code for an input that failed a check, so it is never mistaken for a runtime
failure.
Three more fields describe what the verdict rests on. sample names how many observations
each figure rests on. ungrounded_excluded appears on MOS rules and counts the
streams whose codec has no published impairment value — with grounded_only
off, notes says instead that placeholder scores entered the percentile.
suppressions_applied says whether a lint suppression file was in force, so a
lint_errors count of zero cannot pass for one taken with every rule armed.
A defect in the RULES fails the whole call with invalid_params naming the
rule's index: an unknown metric, an unparseable filter, a severity: scope on
a metric that reads no findings, grounded_only on a metric that reads no MOS,
or a percentile outside 0 to 100. For example:
rule 0: unknown metric 'bogus'. Known metrics: count, asr, lint_errors, mos_p<N>. A percentile is spelled mos_p10, mos_p50, mos_p90 and so on, from mos_p0 (worst stream) to mos_p100 (best)
--expect <FILE>runs this evaluator from the command line and exits withexit_code, so asipnab.expect.tomlin a repository can fail a build. See Fail a build on what a capture shows.
Scanner and abuse signals derived from the capture, and the one tool that turns them into something a firewall can act on.
Recent findings from active detection rules (scanner, fraud, digest, reg-flood). sipnab holds findings in memory only, in a bounded buffer of 1000 entries by default.
| Name | Type | Legal values | If omitted |
|---|---|---|---|
kinds? |
string[]? | Exactly four names: scanner, fraud, digest, reg_flood. Anything else fails with invalid_params naming all four — including reg-flood with a hyphen, which suggests the underscore spelling. |
Findings of every kind. |
since? |
string? |
RFC 3339. Keeps findings recorded strictly after it. A malformed value fails with since must be RFC 3339. |
The whole retained history. |
limit? |
u32? | Ceiling is --mcp-max-rows (1000 by default). Higher clamps to it, 0 means the default. |
50 findings. |
Returns — a page object, not a bare array:
| Field | Type | Description |
|---|---|---|
findings |
object[] | This page of { rule_name, src_ip, detail, timestamp }, newest first. |
returned |
usize | Rows in findings. |
total_matched |
usize | Findings matching kinds and since across the whole retained ring buffer. |
truncated |
bool |
true when matches remain after this page. There is no cursor — narrow with since, or raise limit. |
armed_kinds |
string[] | The detectors this server runs. Empty means it runs none, so findings could only ever be empty. |
detection_armed |
bool |
false when armed_kinds is empty, stated separately so a caller can branch on one field. |
scanner_response |
string | Whether sipnab answers the scanners it detects. off: scanner is not in armed_kinds. detect_only: the server runs with --kill-scanner-detect-only, so it detects scanners and never answers them. not_answering: the server detects scanners and does not answer them, because the server reads a capture file, runs the interactive TUI, or could not start its scanner-kill worker. answering: the scanner-kill worker is running and sends a SIP reply to each detected scanner. |
note |
string? | Present only when no detector runs, saying so in words. |
observation_gaps |
object[] | What an armed detector says it cannot establish from this capture: { rule_name, reason, seen, unestablished, detail }, narrowed by kinds. Always present, empty when there is nothing to say. See below. |
schema_version |
u32 |
1 for this shape. |
capture_identity |
object | Which capture answered — see capture_status. |
Read
armed_kindsbefore you readfindings. An empty findings list means "nothing tripped" only on a server that armed something. On any other it means nothing was watching. Akindsvalue outside the vocabulary fails rather than answering with an empty list. The answer is in this response, so you do not need to callserver_capabilities.
The page fields carry the meanings they do everywhere else on this surface —
search_messages documents the same four.
armed_kinds is per detector: a server started with --kill-scanner alone
returns no fraud findings for any capture, and armed_kinds: ["scanner"]
says fraud detection did not run.
scanner in armed_kinds says only that sipnab detects scanners. Read
scanner_response to learn whether sipnab also answers them. A server started
with --kill-scanner-detect-only reports scanner_response: "detect_only":
it records each scanner as a finding and sends nothing to it.
Arming a rule takes a flag on the server command line, such as --kill-scanner
or --digest-leak. Findings then land in a bounded in-memory ring buffer
(1000 entries by default, --findings-history to change it) and go nowhere
else — stopping the process discards them.
timestamp is the capture time of the packet that triggered the finding, so
on a replayed pcap it is in the capture's own time range. Against
tests/pcap-samples/sip-auth-failure.pcapng, since: "2016-05-17T00:00:00Z"
keeps the finding below, and since: "2026-01-01T00:00:00Z" returns
total_matched: 0.
The example runs against
tests/pcap-samples/sip-auth-failure.pcapng
on a server started with --digest-leak:
// security_findings {}
{
"schema_version": 1,
"findings": [
{
"rule_name": "digest",
"src_ip": "203.0.113.101",
"detail": "⟦untrusted-capture-data⟧WeakAlgorithm: challenge uses algorithm=MD5 (should be SHA-256+)⟦/untrusted-capture-data⟧",
"timestamp": "2016-05-17T08:01:35.432231+00:00"
}
],
"returned": 1,
"total_matched": 1,
"truncated": false,
"armed_kinds": ["digest"],
"detection_armed": true,
"scanner_response": "off",
"observation_gaps": [],
"capture_identity": { "node": "capture-01", "instance": "cc2d618df0ea70d0788a2-2",
"dialog_generation": 8, "stream_generation": 0 },
"source_exhausted": true,
"source_stopped_early": false
}Read observation_gaps beside an empty list. An armed detector
can still fail to see its evidence. reg_flood counts a failure only
when the registrar's 401/407 answers a credentialed REGISTER, so a capture
that holds the REGISTERs and not the answers, such as a one-way tap or a
request-only capture filter, leaves it nothing to count. It then files one
entry here instead of staying silent:
-
reason: "no_answers": the capture shows REGISTERs (seen) and no final response to any of them. sipnab cannot establish any outcome. -
reason: "unanswered": some credentialed REGISTERs (unestablishedofseen) drew no final response inside--reg-flood-transaction-timeout(RFC 3261 Timer F, 32 s by default), so they count as neither failures nor successes.
An entry names no source and never becomes a finding, an alert or a jail line:
a REGISTER count with no outcome behind it is a volume, and reg_flood does not
act on volume. A live server refreshes it every five seconds of capture time,
and the end of a file input settles it.
The same tool on a server started without a detection flag answers with an
empty findings list, armed_kinds: [], detection_armed: false and a note
saying that nothing was watching. armed_kinds: ["digest"] above says the
opposite in the same field: this server watched for digest weaknesses and for
nothing else, so it answers nothing about scanners either way.
A fail2ban filter and jail derived from ONE recorded security finding.
The rule covers one finding, and the response attaches that finding as the evidence, so an operator can review the rule against what triggered it before installing it.
| Name | Type | Legal values | If omitted |
|---|---|---|---|
finding_id |
string |
<rule_name>@<src_ip>@<timestamp> — the three fields security_findings already returns for every finding. |
Required — the call fails. |
sipnab builds the id from the finding's own fields, so the same finding has the same id on a restart or on a second server reading the same capture.
The example runs against tests/pcap-samples/sip-auth-failure.pcapng on a
server started with --digest-leak:
// generate_fail2ban_rule { "finding_id": "[email protected]@2016-05-17T08:01:35.432231+00:00" }
{
"caveats": [
"the failregex matches sipnab's own alert line. Start sipnab with '--alert syslog' (or capture its stderr to the logpath) or the sipnab-digest jail will never see a match.",
"maxretry, findtime and bantime below are fail2ban's conventional starting values, not figures sipnab measured on this traffic. Choose them from your own false-positive tolerance.",
"one finding is evidence that this detector fired, not that every future match is an attacker. The jail bans any source the detector reports, including this one."
],
"evidence": {
"detail": "⟦untrusted-capture-data⟧WeakAlgorithm: challenge uses algorithm=MD5 (should be SHA-256+)⟦/untrusted-capture-data⟧",
"rule_name": "digest",
"src_ip": "203.0.113.101",
"timestamp": "2016-05-17T08:01:35.432231+00:00"
},
"filter_conf": "# Generated by sipnab from finding [email protected]@2016-05-17T08:01:35.432231+00:00\n[Definition]\nfailregex = ^.*\\[ALERT\\] digest src=<HOST> .*$\nignoreregex =\n",
"filter_name": "sipnab-digest",
"filter_path": "/etc/fail2ban/filter.d/sipnab-digest.conf",
"finding_id": "[email protected]@2016-05-17T08:01:35.432231+00:00",
"jail_conf": "[sipnab-digest]\nenabled = true\nfilter = sipnab-digest\nlogpath = /var/log/syslog\nport = 5060,5061\nprotocol = udp\nmaxretry = 3\nfindtime = 600\nbantime = 3600\n",
"jail_path": "/etc/fail2ban/jail.d/sipnab-digest.conf",
"log_line_format": "[ALERT] <rule_name> src=<ip> <detail>",
"schema_version": 1,
"source_exhausted": true,
"source_stopped_early": false
}The failregex matches sipnab's own alert line, the [ALERT] <rule> src=<ip> <detail> form sipnab writes. So the jail sees nothing until sipnab runs with
--alert syslog, or something captures its stderr to the logpath. That is the
first caveat. Without it the jail never matches.
The other two caveats say what the numbers are not. maxretry, findtime and
bantime are fail2ban's conventional starting values rather than figures sipnab
measured on this traffic — choose them from your own false-positive tolerance.
And one finding is evidence that this detector fired, not that every future
match is an attacker: the jail bans any source the detector reports, this one
included. A loopback src_ip adds a fourth caveat, because a jail acting on it
would ban the host from itself.
An id the server does not hold fails with invalid_params and
data.reason: "not_found", and the message lists the ids the server does
hold, up to the row cap, so you can correct a mistyped id without another
call to security_findings:
no finding with id '[email protected]@x'. An id is <rule_name>@<src_ip>@<timestamp>, built from the three fields security_findings returns. This server holds: [email protected]@2016-05-17T08:01:35.432231+00:00
On a server with no detector armed the tool fails with invalid_params and
data.reason: "not_enabled", before it looks for the id:
this server holds no findings: no detection rule was armed, so nothing could have been recorded. Arm one with --kill-scanner, --fraud-detect, --digest-leak or --reg-flood and re-run the capture.
detail arrives fenced: it quotes headers a sender wrote. rule_name does
not, because sipnab chose it, and the tool checks that it is a bare identifier
before writing it into the failregex.