Contributing Parsers and Scenarios

Supporting a new service usually means contributing a parser, a scenario, and a collection that bundles them.

The full walkthroughs are parsers creation and scenarios creation. The shared PR workflow is on Contributing to the Hub.

Parsers

A parser extracts fields. Keep detection logic in the scenario, so others can reuse your parser with their own scenarios. Before you submit a parser:

• Reuse existing grok patterns and expr helpers before writing new ones.
• Set the fields scenarios rely on, in particular the source IP that scenarios use to decide whom to ban.
• Cover the parser with cscli hubtest, using sample logs that include success, failure and edge cases.

Scenarios

Before you submit a scenario:

• Fill the required labels so they match what the scenario detects, since classification and remediation depend on them.
• Test against legitimate traffic too, since a false positive bans real users.
• Explain in the pull request why you chose the capacity and leakspeed, since they set the scenario's sensitivity.

Collections

Bundle tested parsers and scenarios into a collection, following collections format. Its .md should state the goal and include an acquisition example showing how to ingest the relevant logs.

Test your parsers and scenarios

See parser tests and scenario tests. Also check that your items work with the existing ones they depend on. To run tests locally, see Creating a test environment.

Documentation

Add a .md file with the same name as each parser, scenario and collection. The hub renders it: state the item's purpose and anything needed to set it up.