Tag rules
Discovery → Tag rules tags discovered certificates — and can set their owner — on their own:
"certificates whose names end in .example.com and that a public CA vouches for get the tag
external". The rules run over the whole project after scans (at most once every 5 minutes per project)
and every hour, so a new certificate gets its tags without anyone opening it.
Tags typed by hand on a certificate (see Tags and owner) stay as they are: the rules never change them, they only add their own.
A rule
| Field | Rules |
|---|---|
| Name | Required, at most 100 characters, unique in the project (not case-sensitive). |
| Description | Optional, at most 500 characters. |
| On / off | A rule that is off gives nothing; its tags leave the certificates at the next apply. New rules are on. |
| Order | Rules run in order (the arrows in the list). The first matching rule that sets an owner decides the owner. |
| Match | Every condition holds or any condition holds. |
| Conditions | 1 to 10. |
| Tags | Like tags typed by hand: at most 20, each at most 64 characters of letters, digits, spaces and . _ : / -, stored in lower case. |
| Owner | Optional free text, at most 255 characters. |
A rule must give at least one tag or an owner. A project holds at most 100 rules.
Conditions
| Field | Operators | Value |
|---|---|---|
| Common name · Any name (SAN) · Subject · Issuer · Issuer organization | is, contains, starts with, ends with, matches regex | text |
| Key type | is | ECDSA-256, RSA-2048 … or the algorithm alone (RSA) |
| Wildcard certificate · Self-signed · Publicly trusted | is | yes / no |
| Found by source | is | a discovery source |
| Server address | is, contains, starts with, ends with, matches regex, is in range | text, or a range such as 10.0.0.0/8 |
| Server port | is | 1–65535 |
The form shows is for the API operator equals (and for is on yes / no fields) and is in range for in_cidr.
- Text is compared without regard to case. Any name holds when one of the certificate's names matches.
- Subject and Issuer are compared as people read them —
Acme, Inc., without the backslashes the stored form puts before a comma. - Matches regex uses the RE2 syntax and is case-sensitive unless the expression starts with
(?i); it is at most 256 characters, like every value. An invalid expression is refused with the reason. - Publicly trusted means a server serving the certificate now presented a chain the system's trust store accepts. A chain trusted only through a source's own CA certificate does not count, so publicly trusted = no catches certificates of a private CA and self-signed ones.
- A certificate no server serves now (every server that had it stopped answering, or an earlier version a server replaced) has no known trust: it matches neither publicly trusted = yes nor = no, so an old Let's Encrypt version does not get an "internal" tag. Insights counts these certificates as Not served for the same reason. The rule applies again once a server serves the certificate.
- The server conditions (found by source, server address, server port, publicly trusted) hold when any server serving the certificate now matches; servers whose last scan failed do not count.
What the rules give
- Tags — every tag of every matching rule that is on.
- Owner — the owner of the first matching rule (in order) that has one. An owner typed on the certificate by hand wins over it.
They are kept apart from the hand-typed tags and owner. Editing, turning off or deleting a rule changes or removes what it gave. The rule list shows how many certificates each rule matched at the last apply (Counted at the next refresh before the first one); the number opens the inventory filtered by the rule's first tag.
In the inventory, tags given by rules are shown in blue in the Tags column, and on a certificate's Tags and owner card under From tag rules. The tag and owner filters of the inventory and the findings, the exports and the tag suggestions cover both kinds; the export's tag column has both, and its owner column the hand-typed owner or else the rule's.
When rules run
- At every findings refresh: after a scan (at most once every 5 minutes per project) and every hour.
- Right after a rule is saved or deleted, in the background — the certificates show the change within seconds.
When the rules change while an apply is running (for example on another node), the apply runs again with the new rules, so the last change always ends up applied.
The page
The list shows each rule's run order, its conditions in words, its tags and owner, its match count, an on/off switch, Edit and Delete. New rule opens a form with condition rows and a live Matches now count with up to 20 example certificates, worked out from the certificates you can see — nothing is saved until you save the rule.
With no rules yet, four examples can be added with one click: External (publicly trusted = yes,
tag external), Internal (publicly trusted = no, tag internal), Wildcard (tag wildcard)
and Self-signed (tag self-signed). Nothing is added unless you click one.
Access
Anyone who can see the project's discovery can read the rules. Creating, editing, deleting and the Matches now preview need the admin role on the whole project — rules change tags on every certificate of the project, so an admin limited to some granted resources cannot change them. Saves and deletes are limited to 30 a minute per project, previews to 60, and saves and deletes are recorded in the audit log (Discovery Tag Rule Created / Updated / Deleted); a preview stores nothing and is not recorded.
Rules see every certificate of the project. A user limited to some granted discovery sources sees the results only on the certificates its sources found, and the rule list shows such a user no match counts (they are counted over the whole project).
Deleting the project deletes its rules and what they gave.
Only nodes on 1.7.0 apply tag rules. During an upgrade, certificates can miss their rule tags until a 1.7.0 node runs the next apply.
API
GET /api/v1/projects/{projectId}/discovery/tag-rules
POST /api/v1/projects/{projectId}/discovery/tag-rules
PUT /api/v1/projects/{projectId}/discovery/tag-rules/{ruleId}
DELETE /api/v1/projects/{projectId}/discovery/tag-rules/{ruleId}
POST /api/v1/projects/{projectId}/discovery/tag-rules/preview
A rule in the API:
{
"name": "External",
"enabled": true,
"order": 0,
"match": "all",
"conditions": [
{ "field": "san", "op": "ends_with", "value": ".example.com" },
{ "field": "publicly_trusted", "op": "is", "value": "true" }
],
"tags": ["external"],
"owner": "web team"
}
Field names: common_name, san, subject, issuer, issuer_org, key_type, wildcard,
self_signed, publicly_trusted, source (a source id), host, port. Operators: equals,
contains, starts_with, ends_with, matches_regex, in_cidr, is. The list answer carries
fields, the operators each field takes. Discovered certificates carry rule_tags and
rule_owner beside tags and owner. See the API reference.
See also
Video tutorials
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →