# CLI ## Usage Scanner provides a Python CLI for validating and running tests on YAML files to aid in writing detection rules. To install the [Scanner CLI](https://pypi.org/project/scanner-cli/): ``` pip install scanner-cli ``` You will need to provide the API URL of your Scanner instance and an API key. Go to **Settings > API Keys** to find your API URL and API key. You can either set these values as environment variables: ```bash export SCANNER_API_URL= export SCANNER_API_KEY= ``` or provide them as arguments to the CLI: ``` scanner-cli --api-url= --api-key= ``` ## Validate detection rule To validate files: ``` scanner-cli validate -f detections/some_detection.yaml ``` To validate directories: ``` scanner-cli validate -d detections ``` Only YAML files with the correct schema header will be validated. Multiple files or directories can be provided. To recursively search through directories, use the recursive flag `-r`. `validate` checks that the specified files are valid Scanner detection rule files. After validating files, use [`run-tests`](#run-detection-rule-tests)to check that all tests pass before syncing to Scanner. ### Example

Validate detection rules

## Run detection rule tests To run detection rule tests on files: ``` scanner-cli run-tests -f detections/some_detection.yaml ``` To run detection rule tests on directories: ``` scanner-cli run-tests -d detections ``` This will only run tests on YAML files with the correct schema header. Multiple files or directories can be provided. To recursively search through directories, use the recursive flag `-r`. ### Example

Run tests

## Failing tests Tests fail if: * The `expected_detection_result`is true and the provided log events do not trigger a detection in the specified time window * The `expected_detection_result`is false and the provided log events trigger a detection in the specified time window Tips for debugging failed tests: * Check that the log events are hits for `query_text` * Check that the log events have timestamps that fall in the time window specified by `now_timestamp`, `time_range_s` , and `run_frequency_s` * If `now_timestamp`is not provided, the timestamp of the latest log event is used. In both cases, the timestamps are rounded to the next `run_frequency_s`. * Example: if `time_range_s`is 600 seconds, `run_frequency_s`is 60 seconds, and `now_timestamp`is `2024-07-05T10:15:00.000Z`, the time window specified is `2024-07-05T10:05:00.000Z` to `2024-07-05T10:15:00.000Z`. Log events must have timestamps in this time window in order to trigger an alert. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/detections-and-alerting/detection-rules/detection-rules-as-code/cli.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.