YARA rules

You can add your own YARA rules to urlquery. Each new analysis is scanned with them, and matches show up as alerts on the report, in your rule statistics, and as notifications.

This page explains how YARA fits into urlquery. It does not teach the YARA language; for that, see the YARA documentation.

Rule sets and detection rules

Your YARA content has two levels:

Rule set "Phishing kits"
├── Detection rule "kit-a"     one YARA source, like a .yar file
│   ├── rule kit_a_login
│   └── rule kit_a_panel
└── Detection rule "kit-b"
    └── rule kit_b

• Rule set: groups related detection rules. Its owner can rename and delete it. A set shared with your team is visible to your teammates, and they can add detection rules to it too. A detection rule belongs to whoever added it, but deleting the set deletes all its rules.
• Detection rule: one YARA source, like the contents of a .yar file. It can contain more than one YARA rule, and each alert names the YARA rule that matched. Every detection rule is compiled on its own, so a YARA rule can only refer to other YARA rules in the same detection rule.

Manage both under Detection → YARA on urlquery.net, or with the YARA Detection API. A new detection rule's editor shows a starter rule with the urlquery meta fields and commented examples of common strings and conditions; Copy example in the Writing YARA rules panel copies it into the editor. The API is useful for keeping detection rules in a repository and syncing them from CI.

Export on a rule set's page downloads a zip with one .yar file per detection rule, named after the rule. It holds only the sources; descriptions and visibility settings are not included. Import files takes the .yar files back, up to ten at a time.

When detection rules run

• Saving compiles the source; one that doesn't compile is not saved. Limits: UTF-8, 1 MiB, no include.
• Saved detection rules start running within about five minutes.
• Enabled detection rules scan every new analysis, whoever submitted it. To pause one without deleting it, clear Enabled in its editor.
• Existing reports are not rescanned. To see what a rule matches before saving it, test it against a report.
• urlquery may disable a detection rule that matches far more than it should. It then shows as Disabled and stops running until you enable it again in the editor.

Testing a rule

Test against a report in the editor runs your draft on a report you choose and shows every match, without saving anything. Use it before every save: test against a report the rule should match and one it shouldn't. Testing YARA rules walks through it, explains the result, and lists what a test doesn't cover.

Keeping rules quiet

A detection rule scans every new analysis, so a loose rule can match thousands of reports.

• Pick distinctive strings: an unusual endpoint, variable name, or kit marker from your evidence. Generic words such as login or password match a large share of the web on their own.
• Combine strings: all of them or 2 of ($a*) matches far less by accident than any one string.
• Limit the size: filesize < 500KB skips large bundles and downloads.
• Test before saving, and check the rule's statistics after a day.
• Pause a noisy rule by clearing Enabled while you tighten it.

What is scanned

Each piece of captured content is scanned on its own, as one buffer:

Content	Alert trigger
HTTP response bodies the browser received, including HTML, scripts, and downloads	The response URL
JavaScript sources the page ran	The script URL
Files inside downloaded ZIP, 7-Zip, and ISO archives	The file path in the archive

What this means for writing YARA rules:

• Several things are not scanned: the final rendered DOM, the URL itself, request bodies, headers, and screenshots. Text that JavaScript builds after the page loads is only matched where it appears in a script or a response.
• A condition can't span two responses. Write separate YARA rules, or combine their alerts yourself.
• filesize and at offsets refer to the scanned piece, not the whole page.
• A scan stops after one minute per piece. Keep regular expressions bounded.

Alerts

A match adds an alert under detection.analyzer in the report, and on the response or script that matched. It has:

• sensor_name user_<your user ID>;
• a detection_meta object with the detection rule's ID;
• the alert text, verdict, and severity, which you control with optional string fields in the YARA rule's meta: section.

Meta field	Effect	Values
urlquery_alert	The alert text. Without it, the YARA rule's name is used.	Any string
urlquery_verdict	The alert's verdict.	malicious, phishing, malware, suspicious, scam, fraud, audit
urlquery_severity	The alert's severity.	high, medium, low, audit

Missing or unrecognized values become audit, which means informational. See detections and verdicts for how verdicts and severities are weighed.

rule kit_login_form
{
    meta:
        urlquery_alert = "Example kit login form"
        urlquery_verdict = "phishing"
        urlquery_severity = "high"
    strings:
        $form = "/api/collect" ascii nocase
        $post = "POST" ascii
    condition:
        all of them
}

Who sees what

Each detection rule has two settings that are independent of each other. When you're in a team, a new detection rule starts shared with it, for both settings, with teammates allowed to edit; without a team, everything is private.

• Visibility: who can see and use the source. private means only you. team means your team too; teammates can also edit it if you allow it.
• Alert visibility: who sees its alerts on matching reports. private means only you. team means you and your team.

Your detection rules' alerts are never shown to other accounts. Opening a report your detection rule matched still needs normal access to that report: a private report submitted by someone else stays hidden from you even when your detection rule matched it. See report visibility.

Following your matches

• Rule statistics: each detection rule's page on urlquery.net shows its matching reports over 7, 30, or 90 days, broken down by YARA rule and severity, and lists the matching reports you can open. Matches on another account's private reports are not recorded.
• Notifications: while you're signed in to urlquery.net, a match on a report you can open shows a notification. For a detection rule with team alert visibility, your teammates get it too.
• API: GET /public/v2/reports/recent?scope=alerted lists reports with alerts from your or your team's detection rules. See the workflows.