 [](https://twitter.com/CrowdStrike)<br/>
# Caracara Filters
[](https://pypi.org/project/caracara-filters/)
A new filter system for Caracara.
Caracara's previous filter system was inflexible, and tailored too heavily toward the Hosts API module. This project aims to provide an FQL generator that is dialect-aware (i.e., contextual, based on the API module that the request will be sent to).
## Basic Concepts
Instead of declaring each filter as a class, we now have them defined in a dictionary which is significantly easier to work with. Dynamic functionality is provided by storing (partial) functions into each filter.
Each filter derives from the 'default' / base filter, which is configured with identity transforms and validators that return the input value and `True`, respectively, and expects a string input. These settings can be overridden per-filter, and are enforced when a filter is added to the `FQLGenerator` object. We call this process rebasing, as each filter is rebased from a smaller dictionary over the top of the default filter, thus ensuring that all expected values will be present.
When a filter is created, the input goes through these processing stages:
- Validation: the filter's input is passed into a validation function that always returns a `bool`. `True` means that the input is valid, and `False` will raise a `ValueError` exception. At this stage, we also validate the input type; incorrect input types will result in a `TypeError`.
- Transformation: each filter value can be transformed from a human-defined input into something machine-readable, expected by the API. For example, relative timestamps (such as `-30m`) are transformed to a UTC ISO8601 timestamp ready for the Falcon API, and `Containment Pending` is rewritten to `containment_pending` as expected by the Hosts API.
- Storage: the validated, transformed input is stored alongside the FQL property name and the operator (e.g., equality, `>=`, etc.), ready for FQL generation.
When FQL is generated, each of the filters are iterated over and converted to FQL individually, and then chained together with `+` to form an `AND` condition.
## Limitations
We currently only support a limited subset of FQL. For example:
- We *can* generate a condition like "all systems that run Windows or Linux, AND have an IP address in the range 192.168.0.0/16 OR 10.0.0.0/8".
- We *cannot* generate a condition like "all systems that run Windows AND have an IP address in the 192.168.0.0/16 range, as well as all Linux systems in the 10.0.0.0/8 range".
The latter is out of scope as it requires chaining together multiple filters. You can effectively create this functionality for yourself by creating two FQL generators, wrapping their outputs in parentheses, and chaining them together with a `'+'.join()`.
Raw data
{
"_id": null,
"home_page": "https://github.com/CrowdStrike/caracara-filters",
"name": "caracara-filters",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.2,<4.0.0",
"maintainer_email": "",
"keywords": "api,crowdstrike,falcon-platform,fql,query-language,sdk",
"author": "Chris Hammond",
"author_email": "chris.hammond@crowdstrike.com",
"download_url": "https://files.pythonhosted.org/packages/3d/63/b839350b407ec2bae1aca9ab533daf69a0edb0410d5ce060d2dbe6d6074d/caracara_filters-0.2.0.tar.gz",
"platform": null,
"description": " [](https://twitter.com/CrowdStrike)<br/>\n\n# Caracara Filters\n\n[](https://pypi.org/project/caracara-filters/)\n\n\nA new filter system for Caracara.\n\nCaracara's previous filter system was inflexible, and tailored too heavily toward the Hosts API module. This project aims to provide an FQL generator that is dialect-aware (i.e., contextual, based on the API module that the request will be sent to).\n\n## Basic Concepts\n\nInstead of declaring each filter as a class, we now have them defined in a dictionary which is significantly easier to work with. Dynamic functionality is provided by storing (partial) functions into each filter.\n\nEach filter derives from the 'default' / base filter, which is configured with identity transforms and validators that return the input value and `True`, respectively, and expects a string input. These settings can be overridden per-filter, and are enforced when a filter is added to the `FQLGenerator` object. We call this process rebasing, as each filter is rebased from a smaller dictionary over the top of the default filter, thus ensuring that all expected values will be present.\n\nWhen a filter is created, the input goes through these processing stages:\n\n- Validation: the filter's input is passed into a validation function that always returns a `bool`. `True` means that the input is valid, and `False` will raise a `ValueError` exception. At this stage, we also validate the input type; incorrect input types will result in a `TypeError`.\n- Transformation: each filter value can be transformed from a human-defined input into something machine-readable, expected by the API. For example, relative timestamps (such as `-30m`) are transformed to a UTC ISO8601 timestamp ready for the Falcon API, and `Containment Pending` is rewritten to `containment_pending` as expected by the Hosts API.\n- Storage: the validated, transformed input is stored alongside the FQL property name and the operator (e.g., equality, `>=`, etc.), ready for FQL generation.\n\nWhen FQL is generated, each of the filters are iterated over and converted to FQL individually, and then chained together with `+` to form an `AND` condition.\n\n## Limitations\n\nWe currently only support a limited subset of FQL. For example:\n\n- We *can* generate a condition like \"all systems that run Windows or Linux, AND have an IP address in the range 192.168.0.0/16 OR 10.0.0.0/8\".\n- We *cannot* generate a condition like \"all systems that run Windows AND have an IP address in the 192.168.0.0/16 range, as well as all Linux systems in the 10.0.0.0/8 range\".\n\nThe latter is out of scope as it requires chaining together multiple filters. You can effectively create this functionality for yourself by creating two FQL generators, wrapping their outputs in parentheses, and chaining them together with a `'+'.join()`.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "FQL generation engine for Caracara",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/CrowdStrike/caracara-filters",
"Repository": "https://github.com/CrowdStrike/caracara-filters"
},
"split_keywords": [
"api",
"crowdstrike",
"falcon-platform",
"fql",
"query-language",
"sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8abdbbb21926c0345f382da34b06c983b2ffe52b0fdff62a133ed56d147f383b",
"md5": "01e2a27f6056af5ac1f6e62dd57228bd",
"sha256": "853bb9ebf754dc6d707c17b4489dc5c3cf79756071736921b14f60a33cab2b77"
},
"downloads": -1,
"filename": "caracara_filters-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01e2a27f6056af5ac1f6e62dd57228bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.2,<4.0.0",
"size": 18350,
"upload_time": "2023-09-15T12:23:42",
"upload_time_iso_8601": "2023-09-15T12:23:42.543441Z",
"url": "https://files.pythonhosted.org/packages/8a/bd/bbb21926c0345f382da34b06c983b2ffe52b0fdff62a133ed56d147f383b/caracara_filters-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d63b839350b407ec2bae1aca9ab533daf69a0edb0410d5ce060d2dbe6d6074d",
"md5": "0a460019e95d17db0fa4e16b700b0884",
"sha256": "cc0813a7e0cf64b5e9c20cee289610cd25f7a03b2d84988e5fa21333a2485d5e"
},
"downloads": -1,
"filename": "caracara_filters-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "0a460019e95d17db0fa4e16b700b0884",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.2,<4.0.0",
"size": 13252,
"upload_time": "2023-09-15T12:23:43",
"upload_time_iso_8601": "2023-09-15T12:23:43.550622Z",
"url": "https://files.pythonhosted.org/packages/3d/63/b839350b407ec2bae1aca9ab533daf69a0edb0410d5ce060d2dbe6d6074d/caracara_filters-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-15 12:23:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CrowdStrike",
"github_project": "caracara-filters",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "caracara-filters"
}
JSON
