Detection rules

Plonix recognises the technologies behind every host you browse (servers, frameworks, CMSs, CDNs, WAFs, identity providers, exposed admin consoles) using declarative detection rules. Rules ship in rule packs that anyone can write, share and install from a file, a URL or the store. The engine's Discovery layer runs them over captured traffic, and the results show up per host in plonix tech, in GET /api/tech, and in the Map.

$ plonix tech
shop.acme.test
  web-server     nginx 1.25.3               100%  response header server ~ nginx/1.25.3 (#3)
  language       PHP 8.2.12                 100%  response header x-powered-by ~ PHP/8.2.12 (#3)
  cms            WordPress 6.4.2            100%  path ~ /wp-content/ (#5)

Every detection carries its evidence: the condition that matched, a sample of what it matched, and the exchange id, so plonix show 3 takes you straight to the proof.

Contents#

• How detection runs
• Trust boundary
• Writing a rule
• Conditions
• Rule packs
• Installing and managing packs
• The store
• Limits
• Contributing a pack

How detection runs#

• Detection is passive. It only reads traffic that the proxy has already captured. A rule never causes a request to be sent.
• It runs on demand over each host's most recent 300 exchanges, so rules you install later apply to everything you already captured. There is nothing to re-browse.
• The engine notices when packs are added or removed (rules/lock.json changes) and reloads them. There is no restart.
• Built-in packs are always loaded. Installed packs are loaded after them.
• When two rules or packs detect the same id, Plonix shows one entry with the higher confidence and keeps any version either of them found.
• implies adds related technologies (WordPress implies PHP), marked implied by … and carrying the confidence of the rule that implied them. Direct evidence always wins over an implication.

Trust boundary#

Rule packs come from people you don't know. Plonix treats every pack as untrusted data and nothing more:

What a pack can do is be wrong: claim a technology that isn't there, or miss one that is. That's why every detection shows its evidence and confidence, and why the store is reviewed (see Contributing a pack).

Writing a rule#

{
  "id": "wordpress",
  "name": "WordPress",
  "category": "cms",
  "website": "https://wordpress.org",
  "confidence": 100,
  "match": "any",
  "implies": ["php"],
  "conditions": [
    { "path": "^/wp-(?:content|includes|admin|json)/" },
    { "body": "<meta name=\"generator\" content=\"WordPress ?([\\d.]+)?", "version": "$1" },
    { "cookie": "wordpress_test_cookie" }
  ]
}

Conditions#

Each condition sets exactly one target:

For the named targets (header, request_header, cookie, query_param), the target's presence alone is a match unless you add regex. For path, host and body, the value is the pattern, and regex isn't allowed.

Patterns use Rust regex syntax and are case-insensitive. Remember to escape backslashes in JSON ("\\d").

Versions. Add "version": "$1" to pull a version out of a capture group. Templates may only contain $1 to $9 and the characters [A-Za-z0-9._-], and they must refer to a group the pattern actually has. If one exchange shows Server: nginx and a later one shows Server: nginx/1.25.3, Plonix reports 1.25.3.

{ "header": "Server", "regex": "^nginx(?:/([\\d.]+))?", "version": "$1" }
{ "cookie": "incap_ses_*" }
{ "query_param": "response_type", "regex": "id_token" }
{ "request_header": "Authorization", "regex": "^Bearer eyJ[A-Za-z0-9_-]+\\.eyJ" }

Rule packs#

A pack is one JSON file:

{
  "plonix_pack": 1,
  "name": "acme-internal",
  "version": "1.0.0",
  "description": "Acme's in-house gateway and auth service",
  "author": "Acme red team",
  "license": "Apache-2.0",
  "homepage": "https://example.com/plonix-rules",
  "rules": [ … ]
}

A pack's checksum is the SHA-256 of the file's exact bytes. It lives outside the pack (in the store index, or on the command line with --sha256), because a file can't vouch for itself.

Validation reports every problem at once, with its location:

$ plonix rules check bad.json
error: invalid rule pack:
  - rules[0] (acme-gateway): category: `rootkit` is not one of web-server, language, …

Installing and managing packs#

plonix rules                                   # packs in effect: built-in and installed
plonix rules check ./my-pack.json              # validate without installing; prints the sha256
plonix rules add ./my-pack.json                # install from a file
plonix rules add https://example.com/pack.json --sha256 <hex>   # from a URL, pinned
plonix rules remove my-pack
plonix tech                                    # what the rules found, per host
plonix tech shop.example.com

rules add without --sha256 pins whatever it downloaded and prints the checksum, so later tampering is still detected. Pass --sha256 to make sure you get the exact build you reviewed.

Installed packs live in ~/.plonix/rules/ (or $PLONIX_HOME/rules/):

rules/
├── lock.json          name → version, sha256, source, installed_at
└── packs/<name>.json  the exact bytes that were verified

Plonix ships six packs, five built in and one in the store:

The store#

The store is a static JSON index that can be hosted anywhere: the Plonix repository (the default), a fork, an internal web server, or a folder on disk. There is no server to run and no account.

{
  "plonix_index": 1,
  "name": "Plonix community store",
  "packages": [
    {
      "name": "admin-panels",
      "kind": "rules",
      "version": "1.0.0",
      "description": "DevOps tools and admin consoles that are often exposed by mistake.",
      "author": "Plonix contributors",
      "url": "packs/admin-panels.json",
      "sha256": "…64 hex characters…"
    }
  ]
}

• A relative url resolves against the index's own location and may not contain ... An absolute url must be https://.
• kind is rules today. extension entries are sandboxed code extensions; see extensions.md.
• Installing downloads the pack, checks its SHA-256 against the index, checks that its name and version match the entry, validates it, and only then writes it to disk.

plonix store                         # list the community store
plonix store list graphql            # filter by name or description
plonix store install admin-panels
plonix store update                  # upgrade installed packs that have a newer version
plonix store --index https://intranet.example.com/plonix/index.json   # or $PLONIX_STORE_INDEX
plonix store --index ./my-store/index.json                            # a local store

The index is the root of trust: whoever controls it decides which bytes are acceptable. Use the default community index, one you host yourself, or one from a team you trust. Teams can run a private store by putting an index.json and their packs on any internal https host.

Limits#

Contributing a pack#

1. Write your pack and run plonix rules check your-pack.json until it's clean. Test it against real traffic with plonix rules add and plonix tech.
2. Prefer specific signals (a distinctive header, a framework-specific cookie) over generic ones, and lower confidence for anything that could be a coincidence.
3. Reuse existing ids for existing technologies so detections merge instead of duplicating.
4. Open a pull request that adds store/packs/<name>.json and an entry in store/index.json with the sha256 printed by plonix rules check. cargo test (and CI) checks that every index entry matches its file.

Reviewers check that patterns are specific, categories are right, and nothing in the pack is surprising. The checksum in the index is what makes that review stick: once merged, users install exactly the bytes that were reviewed.