Merge pull request #18 from CrowdStrike/bugfix/10-11-12/Sep2024Cleanup

Version 1.0.0

.flake8

@@ -1,2 +1,3 @@
 [flake8]
 max-line-length = 100
+extend-ignore = E203

.github/dependabot.yml

@@ -0,0 +1,13 @@
+---
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 10

.github/workflows/code-quality.yml

@@ -1,4 +1,4 @@
-name: Caracara Filters Code Quality
+name: Caracara Filters Code Quality and Test Coverage
 on:
   push:
     paths:
@@ -15,24 +15,44 @@ jobs:
   codequality:
     strategy:
       matrix:
-        python-version: ["3.7", "3.9", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13.0-rc.2"]
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install Poetry via pipx
       run: pipx install poetry
+
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
         cache: 'poetry'
+
     - name: Install dependencies
       run: poetry install
+
     - name: Lint package source with flake8
       run: poetry run flake8 caracara_filters/ --show-source --statistics
+
     - name: Lint package source with pylint
       if: success() || failure()
       run: poetry run pylint caracara_filters/
+
     - name: Lint package docstrings and comments with pydocstyle
       if: success() || failure()
       run: poetry run pydocstyle caracara_filters/
+
+    - name: Lint imports with isort
+      if: success() || failure()
+      run: poetry run isort -c caracara_filters/
+
+    - name: Lint package with black
+      if: success() || failure()
+      run: poetry run black -l 100 --check caracara_filters/
+
+    - name: Run pytest via Coverage
+      if: success() || failure()
+      run: poetry run coverage run --source=caracara_filters -m pytest -s
+
+    - name: Get Coverage Report
+      run: poetry run coverage report

caracara_filters/__init__.py

@@ -2,8 +2,9 @@
 
 This module contains a new implementation of an FQL generator designed to plug in to Caracara.
 """
+
 __all__ = [
-    'FQLGenerator',
+    "FQLGenerator",
 ]
 
 from caracara_filters.fql import FQLGenerator

caracara_filters/common/__init__.py

@@ -3,14 +3,13 @@
 This module contains functionality shared predominantly between transforms and validators, such as
 shared regular expressions.
 """
+
 __all__ = [
-    'FILTER_OPERATORS',
-    'IP_ADDRESS_RE',
-    'PLATFORMS',
-    'RELATIVE_TIMESTAMP_RE',
+    "FILTER_OPERATORS",
+    "IP_ADDRESS_RE",
+    "PLATFORMS",
+    "RELATIVE_TIMESTAMP_RE",
 ]
 
-from caracara_filters.common.constants import FILTER_OPERATORS
-from caracara_filters.common.constants import PLATFORMS
-from caracara_filters.common.regex import IP_ADDRESS_RE
-from caracara_filters.common.regex import RELATIVE_TIMESTAMP_RE
+from caracara_filters.common.constants import FILTER_OPERATORS, PLATFORMS
+from caracara_filters.common.regex import IP_ADDRESS_RE, RELATIVE_TIMESTAMP_RE

caracara_filters/common/constants.py

@@ -1,12 +1,12 @@
 """Caracara Filters: Constants."""
 
 FILTER_OPERATORS = {
-    "EQUAL": '',
-    "NOT": '!',
-    "GREATER": '>',
-    "GTE": '>=',
-    "LESS": '<',
-    "LTE": '<=',
+    "EQUAL": "",
+    "NOT": "!",
+    "GREATER": ">",
+    "GTE": ">=",
+    "LESS": "<",
+    "LTE": "<=",
 }
 
-PLATFORMS = ['Linux', 'Mac', 'Windows']
+PLATFORMS = ["Linux", "Mac", "Windows"]

caracara_filters/common/regex.py

@@ -1,11 +1,7 @@
 """Caracara Filters: Shared Regular Expressions."""
-import re
 
+import re
 
-IP_ADDRESS_RE = re.compile(
-    r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"
-)
+IP_ADDRESS_RE = re.compile(r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")
 
-RELATIVE_TIMESTAMP_RE = re.compile(
-    r"^(?P<sign>[-+])(?P<number>\d+)(?P<scale>(s|m|h|d))$"
-)
+RELATIVE_TIMESTAMP_RE = re.compile(r"^(?P<sign>[-+])(?P<number>\d+)(?P<scale>(s|m|h|d))$")

caracara_filters/dialects/__init__.py

@@ -6,18 +6,17 @@
 """
 
 __all__ = [
-    'DIALECTS',
-    'HOSTS_FILTERS',
-    'PREVENTION_POLICIES_FILTERS',
-    'RESPONSE_POLICIES_FILTERS',
-    'RTR_FILTERS',
-    'USERS_FILTERS',
-    'default_filter',
-    'rebase_filters_on_default',
+    "DIALECTS",
+    "HOSTS_FILTERS",
+    "PREVENTION_POLICIES_FILTERS",
+    "RESPONSE_POLICIES_FILTERS",
+    "RTR_FILTERS",
+    "USERS_FILTERS",
+    "default_filter",
+    "rebase_filters_on_default",
 ]
 
-from caracara_filters.dialects._base import BASE_FILTERS
-from caracara_filters.dialects._base import default_filter
+from caracara_filters.dialects._base import BASE_FILTERS, default_filter
 from caracara_filters.dialects._merge import rebase_filters_on_default
 from caracara_filters.dialects.hosts import HOSTS_FILTERS
 from caracara_filters.dialects.prevention_policies import PREVENTION_POLICIES_FILTERS

caracara_filters/dialects/_base.py

@@ -3,14 +3,14 @@
 This file contains a base set of 'common' FQL parameters that may be used across multiple
 dialects.
 """
+
 from functools import partial
 from typing import Any, Dict
 
 from caracara_filters.common import PLATFORMS
 from caracara_filters.dialects._merge import rebase_filters_on_default
 from caracara_filters.transforms import identity_transform
-from caracara_filters.validators import identity_validator
-from caracara_filters.validators import options_validator
+from caracara_filters.validators import identity_validator, options_validator
 
 default_filter = {
     "data_type": str,
@@ -19,7 +19,7 @@
     "nullable": False,
     "transform": identity_transform,
     "validator": identity_validator,
-    "valid_operators": ['EQUAL'],
+    "valid_operators": ["EQUAL"],
 }
 
 name_filter = {

caracara_filters/dialects/_merge.py

@@ -3,12 +3,12 @@
 This code file will merge the filter dictionaries using mergedeep
 so that a resultant filter can exist.
 """
+
 from typing import Any, Dict
 
 
 def rebase_filters_on_default(
-    default_filter: Dict[str, Any],
-    filters: Dict[str, Dict[str, Any]]
+    default_filter: Dict[str, Any], filters: Dict[str, Dict[str, Any]]
 ) -> None:
     """Rebase every filter on a default base filter.
 

caracara_filters/dialects/hosts.py

@@ -2,15 +2,13 @@
 
 This module contains filters that are specific to the Hosts API.
 """
+
 from functools import partial
 from typing import Any, Dict
 
-from caracara_filters.dialects._base import default_filter
-from caracara_filters.dialects._base import rebase_filters_on_default
+from caracara_filters.dialects._base import default_filter, rebase_filters_on_default
 from caracara_filters.transforms import relative_timestamp_transform
-from caracara_filters.validators import options_validator
-from caracara_filters.validators import relative_timestamp_validator
-
+from caracara_filters.validators import options_validator, relative_timestamp_validator
 
 _containment_value_map = {
     "Contained": "contained",
@@ -40,10 +38,13 @@ def user_readable_string_transform(map_dict: Dict[str, str], input_str: str) ->
     "fql": "status",
     "help": "Filter by a host's network containment status.",
     "transform": partial(user_readable_string_transform, _containment_value_map),
-    "validator": partial(options_validator, [
-        *_containment_value_map.keys(),
-        *_containment_value_map.values(),
-    ]),
+    "validator": partial(
+        options_validator,
+        [
+            *_containment_value_map.keys(),
+            *_containment_value_map.values(),
+        ],
+    ),
 }
 
 hosts_device_id_filter = {
@@ -59,6 +60,16 @@ def user_readable_string_transform(map_dict: Dict[str, str], input_str: str) ->
     ),
 }
 
+hosts_external_ip_address_filter = {
+    "fql": "external_ip",
+    "help": (
+        "This filter accepts an IP address string associated with a remote network, e.g. "
+        "123.234.123.234, or 123.234.0.0/16 to cover the /16 range. You can also comma delimit "
+        "strings for multiple matches, e.g., 123.234.123.234,100.200.100.200 to target hosts with "
+        "each of those IP addresses, or provide a Python list of IP address strings."
+    ),
+}
+
 hosts_first_seen_filter = {
     "fql": "first_seen",
     "multivariate": False,
@@ -127,9 +138,9 @@ def user_readable_string_transform(map_dict: Dict[str, str], input_str: str) ->
     "fql": "local_ip",
     "help": (
         "This filter accepts an IP address string associated with a network card, e.g. "
-        "172.16.1.2 or 172.16.* to cover the /16 range. You can also comma delimit strings "
+        "172.16.1.2 or 172.16.0.0/16 to cover the /16 range. You can also comma delimit strings "
         "for multiple matches, e.g., 172.16.1.2,172.16.1.3 to target hosts with each of those "
-        "IPs, or provide a Python list of IP strings."
+        "IP addresses, or provide a Python list of IP address strings."
     ),
 }
 
@@ -149,6 +160,7 @@ def user_readable_string_transform(map_dict: Dict[str, str], input_str: str) ->
     ),
 }
 
+
 hosts_role_filter = {
     "fql": "product_type_desc",
     "transform": partial(user_readable_string_transform, _role_map),
@@ -188,6 +200,8 @@ def user_readable_string_transform(map_dict: Dict[str, str], input_str: str) ->
     "deviceid": hosts_device_id_filter,
     "device_id": hosts_device_id_filter,  # pythonic
     "domain": hosts_domain_filter,
+    "external": hosts_external_ip_address_filter,
+    "external_ip": hosts_external_ip_address_filter,  # pythonic
     "firstseen": hosts_first_seen_filter,
     "first_seen": hosts_first_seen_filter,  # pythonic
     "groupid": hosts_group_id_filter,

caracara_filters/dialects/prevention_policies.py

@@ -4,8 +4,8 @@
 This code may be merged into a more generic policies dialect, depending on the overlaps
 in data structures.
 """
-from caracara_filters.dialects._base import default_filter
-from caracara_filters.dialects._base import rebase_filters_on_default
+
+from caracara_filters.dialects._base import default_filter, rebase_filters_on_default
 
 PREVENTION_POLICIES_FILTERS = {}
 rebase_filters_on_default(default_filter, PREVENTION_POLICIES_FILTERS)

caracara_filters/dialects/response_policies.py

@@ -4,8 +4,8 @@
 This code may be merged into a more generic policies dialect, depending on the overlaps
 in data structures.
 """
-from caracara_filters.dialects._base import default_filter
-from caracara_filters.dialects._base import rebase_filters_on_default
+
+from caracara_filters.dialects._base import default_filter, rebase_filters_on_default
 
 RESPONSE_POLICIES_FILTERS = {}
 rebase_filters_on_default(default_filter, RESPONSE_POLICIES_FILTERS)

caracara_filters/dialects/rtr.py

@@ -2,14 +2,13 @@
 
 This module contains filters that are specific to the RTR API.
 """
+
 from functools import partial
 from typing import Any, Dict
 
-from caracara_filters.dialects._base import default_filter
-from caracara_filters.dialects._base import rebase_filters_on_default
+from caracara_filters.dialects._base import default_filter, rebase_filters_on_default
 from caracara_filters.validators import options_validator
 
-
 RTR_COMMANDS = [
     "cat",
     "cd",

caracara_filters/dialects/users.py

@@ -2,11 +2,10 @@
 
 This module contains filters that are specific to the User Management API.
 """
-from typing import Any, Dict
 
-from caracara_filters.dialects._base import default_filter
-from caracara_filters.dialects._base import rebase_filters_on_default
+from typing import Any, Dict
 
+from caracara_filters.dialects._base import default_filter, rebase_filters_on_default
 
 users_assigned_cids_filter = {
     "fql": "assigned_cids",