falcon-toolkit 3.3.0__tar.gz → 3.4.0__tar.gz

falcon_toolkit-3.3.0/README.md → falcon_toolkit-3.4.0/PKG-INFO

@@ -1,3 +1,41 @@
+Metadata-Version: 2.1
+Name: falcon-toolkit
+Version: 3.4.0
+Summary: Toolkit to interface with CrowdStrike Falcon via the API
+Home-page: http://github.com/CrowdStrike/Falcon-Toolkit
+License: MIT
+Keywords: automation,cli,crowdstrike,endpoint-protection,falcon,falcon-platform
+Author: Chris Hammond
+Author-email: chris.hammond@crowdstrike.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Terminals
+Requires-Dist: caracara (>=0.7.0,<0.8.0)
+Requires-Dist: click (>=8.1.3,<9.0.0)
+Requires-Dist: click-option-group (>=0.5.6,<0.6.0)
+Requires-Dist: click-spinner (>=0.1.10,<0.2.0)
+Requires-Dist: cmd2 (>=2.4,<3.0)
+Requires-Dist: colorama (>=0.4.5,<0.5.0)
+Requires-Dist: keyring (>=24,<26)
+Requires-Dist: platformdirs (>=4.2.0,<5.0.0)
+Requires-Dist: prompt-toolkit (>=3.0.43,<4.0.0)
+Requires-Dist: setuptools (>=69.0,<70.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Project-URL: Repository, http://github.com/CrowdStrike/Falcon-Toolkit
+Description-Content-Type: text/markdown
+
 <!--markdownlint-disable MD033-->
 # Falcon Toolkit
 
@@ -21,8 +59,9 @@ The toolkit provides:
 - Multiple profile support, including support for MSSP / Falcon Flight Control configurations.
 - A shell allowing you to interface with many hosts via RTR at once, and get the output via CSV.
 - Scriptability! You can program the shell by providing pre-written routines via a file on disk, and a full Python extensibility API is provided.
-- Prevention policy import and export
-- Response policy import and export
+- Prevention policy import and export.
+- Response policy import and export.
+- Contain and uncontain systems in bulk, according to filters or a list of device IDs.
 - More functionality is coming soon! Want more functionality? Open an [Issue](https://github.com/CrowdStrike/Falcon-Toolkit/issues/new)!
 
 Since this is built on top of Caracara, you get a bunch of great functionality and flexibility free, including the ability to filter hosts using dynamically generated FQL queries, full debug logging where desired, Falcon Flight Control integration, and more! Plus, the tool is lightning quick as it leverages Caracara's parallelisation tricks to pull more information quickly.
@@ -182,17 +221,19 @@ Two types of configuration backends are provided out of the box: the default, wh
 
 Your API keys should have the following scopes enabled in the Falcon dashboard:
 
-| &darr; API Scopes // Commands &rarr; | `host_search` | `shell` | `policies`<br>(Prevention) | `policies`<br>(Response)  |
-|--------------------------------------|:-------------:|:-------:|:--------------------------:|:-------------------------:|
-| **Falcon Flight Control: Read**      | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* |
-| **Hosts: Read**                      |       X       |    X    |                            |                           |
-| **Prevention Policies: Read**        |               |         | X<br>`describe` / `export` sub-commands |              |
-| **Prevention Policies: Write**       |               |         | X<br>`import` sub-command  |                           |
-| **Real Time Response: Read**         |               |    X    |                            |                           |
-| **Real Time Response: Write**        |               |    X    |                            |                           |
-| **Real Time Response: Admin**        |               |    X<br>*for admin commands*    |    |                           |
-| **Response Policies: Read**          |               |         |                            | X<br>`describe` / `export` sub-commands |
-| **Response Policies: Write**         |               |         |                            | X<br>`import` sub-command |
+| &darr; API Scopes // Commands &rarr; | `host_search` | `shell` | `policies`<br>(Prevention) | `policies`<br>(Response)  | `containment`<br>Host Containment | `maintenance_token`<br>Maintenance Tokens |
+|--------------------------------------|:-------------:|:-------:|:--------------------------:|:-------------------------:|:---------------------------------:|:-----------------------------------------:|
+| **Falcon Flight Control: Read**      | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | | |
+| **Hosts: Read**                      |       X       |    X    |                            |                           | X | X |
+| **Hosts: Write**                     |               |         |                            |                           | X | |
+| **Prevention Policies: Read**        |               |         | X<br>`describe` / `export` sub-commands |              |   | |
+| **Prevention Policies: Write**       |               |         | X<br>`import` sub-command  |                           |   | |
+| **Real Time Response: Read**         |               |    X    |                            |                           |   | |
+| **Real Time Response: Write**        |               |    X    |                            |                           |   | |
+| **Real Time Response: Admin**        |               |    X<br>*for admin commands*    |    |                           |   | |
+| **Response Policies: Read**          |               |         |                            | X<br>`describe` / `export` sub-commands |   | |
+| **Response Policies: Write**         |               |         |                            | X<br>`import` sub-command |   | |
+| **Sensor Update Policies: Write**    |               |         |                            |                           |   | X |
 
 ### Showing Your Profiles
 
@@ -355,6 +396,73 @@ Some example usages of this functionality are as follows:
 
 </details>
 
+## Maintenance Tokens
+
+You can fetch maintenance tokens for systems within your Falcon tenant, or retrieve the bulk maintenance token.
+
+### Examples
+
+Show the bulk maintenance token:
+
+```shell
+$ falcon -p MyCompany maintenance_token -b
+Getting the bulk maintenance token
+Bulk maintenance token: redactedexample12345
+WARNING: this token must be kept safe, as it can uninstall all Falcon sensors!
+```
+
+Show a token for a specific system located by hostname:
+
+```shell
+$ falcon -p MyCompany maintenance_token -f Hostname=MY-TEST-BOX-1
+```
+
+Show maintenance tokens for a list of device IDs provided on the command line:
+
+```shell
+$ falcon -p MyCompany maintenance_token -d aid1,aid2,...
+```
+
+## Network Containment
+
+You can `contain` and `uncontain` systems through Falcon Toolkit. Network containment restricts the network connectivity of matching systems to just the Falcon Platform.
+
+The containment functionality accepts the same command line parameters as `host_search` and `shell` (`-d`, `-df`, or multiple instances of `-f` to apply Falcon filters).
+
+### Examples
+
+Network contain all systems that match the FQL hostname pattern `DEVTEST*`:
+
+```shell
+$ falcon -p MyCompany containment -f Hostname=DEVTEST\* contain
+...
+```
+
+Lift the containment status on the same machines:
+
+```shell
+$ falcon -p MyCompany containment -f Hostname=DEVTEST\* uncontain
+...
+```
+
+Network contain specific systems by AID:
+
+```shell
+$ falcon -p MyCompany containment -d aid1,aid2,aid3 contain
+...
+```
+
+Network contain all systems in a CID:
+
+```shell
+$ falcon -p MyCompany containment contain
+You did not specify any parameters. This command will manage the containment status of ALL devices in the Falcon tenant!
+You must enter the string "I AM SURE!" to proceed.
+Are you sure? I AM SURE!
+...
+```
+
+
 ## Policy Manipulation
 
 You can `describe`, `import` and `export` two types of policies: Prevention and Response. The three verbs are applied to the `falcon policies` command to specify what you would like to do with policies, and a command line switch is used to specify the policy type to work with. Exported policies are written to disk as JSON with some Falcon Toolkit-specific data needed to import a policy back again.
@@ -408,3 +516,4 @@ Furthermore, GitHub Discussions provide the community with means to communicate.
 *Security issues should be raised to our [Security team](mailto:security@crowdstrike.com) and [Chris Hammond](mailto:Chris.Hammond@crowdstrike.com).*
 
 Thank you for using the Falcon Toolkit! We hope it is as useful to the Falcon user community as it is to us.
+

falcon_toolkit-3.3.0/PKG-INFO → falcon_toolkit-3.4.0/README.md

@@ -1,39 +1,3 @@
-Metadata-Version: 2.1
-Name: falcon-toolkit
-Version: 3.3.0
-Summary: Toolkit to interface with CrowdStrike Falcon via the API
-Home-page: http://github.com/CrowdStrike/Falcon-Toolkit
-License: MIT
-Keywords: automation,cli,crowdstrike,endpoint-protection,falcon,falcon-platform
-Author: Chris Hammond
-Author-email: chris.hammond@crowdstrike.com
-Requires-Python: >=3.9,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Natural Language :: English
-Classifier: Operating System :: MacOS
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Topic :: Security
-Classifier: Topic :: System :: Shells
-Classifier: Topic :: Terminals
-Requires-Dist: caracara (>=0.5.1,<0.6.0)
-Requires-Dist: click (>=8.1.3,<9.0.0)
-Requires-Dist: click-option-group (>=0.5.3,<0.6.0)
-Requires-Dist: click-spinner (>=0.1.10,<0.2.0)
-Requires-Dist: cmd2 (>=2.4,<3.0)
-Requires-Dist: colorama (>=0.4.5,<0.5.0)
-Requires-Dist: keyring (>=23,<25)
-Requires-Dist: pick (>=2.0.2,<3.0.0)
-Requires-Dist: platformdirs (>=3.5.1,<4.0.0)
-Requires-Dist: tabulate (>=0.9.0,<0.10.0)
-Project-URL: Repository, http://github.com/CrowdStrike/Falcon-Toolkit
-Description-Content-Type: text/markdown
-
 <!--markdownlint-disable MD033-->
 # Falcon Toolkit
 
@@ -57,8 +21,9 @@ The toolkit provides:
 - Multiple profile support, including support for MSSP / Falcon Flight Control configurations.
 - A shell allowing you to interface with many hosts via RTR at once, and get the output via CSV.
 - Scriptability! You can program the shell by providing pre-written routines via a file on disk, and a full Python extensibility API is provided.
-- Prevention policy import and export
-- Response policy import and export
+- Prevention policy import and export.
+- Response policy import and export.
+- Contain and uncontain systems in bulk, according to filters or a list of device IDs.
 - More functionality is coming soon! Want more functionality? Open an [Issue](https://github.com/CrowdStrike/Falcon-Toolkit/issues/new)!
 
 Since this is built on top of Caracara, you get a bunch of great functionality and flexibility free, including the ability to filter hosts using dynamically generated FQL queries, full debug logging where desired, Falcon Flight Control integration, and more! Plus, the tool is lightning quick as it leverages Caracara's parallelisation tricks to pull more information quickly.
@@ -218,17 +183,19 @@ Two types of configuration backends are provided out of the box: the default, wh
 
 Your API keys should have the following scopes enabled in the Falcon dashboard:
 
-| &darr; API Scopes // Commands &rarr; | `host_search` | `shell` | `policies`<br>(Prevention) | `policies`<br>(Response)  |
-|--------------------------------------|:-------------:|:-------:|:--------------------------:|:-------------------------:|
-| **Falcon Flight Control: Read**      | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* |
-| **Hosts: Read**                      |       X       |    X    |                            |                           |
-| **Prevention Policies: Read**        |               |         | X<br>`describe` / `export` sub-commands |              |
-| **Prevention Policies: Write**       |               |         | X<br>`import` sub-command  |                           |
-| **Real Time Response: Read**         |               |    X    |                            |                           |
-| **Real Time Response: Write**        |               |    X    |                            |                           |
-| **Real Time Response: Admin**        |               |    X<br>*for admin commands*    |    |                           |
-| **Response Policies: Read**          |               |         |                            | X<br>`describe` / `export` sub-commands |
-| **Response Policies: Write**         |               |         |                            | X<br>`import` sub-command |
+| &darr; API Scopes // Commands &rarr; | `host_search` | `shell` | `policies`<br>(Prevention) | `policies`<br>(Response)  | `containment`<br>Host Containment | `maintenance_token`<br>Maintenance Tokens |
+|--------------------------------------|:-------------:|:-------:|:--------------------------:|:-------------------------:|:---------------------------------:|:-----------------------------------------:|
+| **Falcon Flight Control: Read**      | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | X<br>*When using parent<br>CID API Keys* | | |
+| **Hosts: Read**                      |       X       |    X    |                            |                           | X | X |
+| **Hosts: Write**                     |               |         |                            |                           | X | |
+| **Prevention Policies: Read**        |               |         | X<br>`describe` / `export` sub-commands |              |   | |
+| **Prevention Policies: Write**       |               |         | X<br>`import` sub-command  |                           |   | |
+| **Real Time Response: Read**         |               |    X    |                            |                           |   | |
+| **Real Time Response: Write**        |               |    X    |                            |                           |   | |
+| **Real Time Response: Admin**        |               |    X<br>*for admin commands*    |    |                           |   | |
+| **Response Policies: Read**          |               |         |                            | X<br>`describe` / `export` sub-commands |   | |
+| **Response Policies: Write**         |               |         |                            | X<br>`import` sub-command |   | |
+| **Sensor Update Policies: Write**    |               |         |                            |                           |   | X |
 
 ### Showing Your Profiles
 
@@ -391,6 +358,73 @@ Some example usages of this functionality are as follows:
 
 </details>
 
+## Maintenance Tokens
+
+You can fetch maintenance tokens for systems within your Falcon tenant, or retrieve the bulk maintenance token.
+
+### Examples
+
+Show the bulk maintenance token:
+
+```shell
+$ falcon -p MyCompany maintenance_token -b
+Getting the bulk maintenance token
+Bulk maintenance token: redactedexample12345
+WARNING: this token must be kept safe, as it can uninstall all Falcon sensors!
+```
+
+Show a token for a specific system located by hostname:
+
+```shell
+$ falcon -p MyCompany maintenance_token -f Hostname=MY-TEST-BOX-1
+```
+
+Show maintenance tokens for a list of device IDs provided on the command line:
+
+```shell
+$ falcon -p MyCompany maintenance_token -d aid1,aid2,...
+```
+
+## Network Containment
+
+You can `contain` and `uncontain` systems through Falcon Toolkit. Network containment restricts the network connectivity of matching systems to just the Falcon Platform.
+
+The containment functionality accepts the same command line parameters as `host_search` and `shell` (`-d`, `-df`, or multiple instances of `-f` to apply Falcon filters).
+
+### Examples
+
+Network contain all systems that match the FQL hostname pattern `DEVTEST*`:
+
+```shell
+$ falcon -p MyCompany containment -f Hostname=DEVTEST\* contain
+...
+```
+
+Lift the containment status on the same machines:
+
+```shell
+$ falcon -p MyCompany containment -f Hostname=DEVTEST\* uncontain
+...
+```
+
+Network contain specific systems by AID:
+
+```shell
+$ falcon -p MyCompany containment -d aid1,aid2,aid3 contain
+...
+```
+
+Network contain all systems in a CID:
+
+```shell
+$ falcon -p MyCompany containment contain
+You did not specify any parameters. This command will manage the containment status of ALL devices in the Falcon tenant!
+You must enter the string "I AM SURE!" to proceed.
+Are you sure? I AM SURE!
+...
+```
+
+
 ## Policy Manipulation
 
 You can `describe`, `import` and `export` two types of policies: Prevention and Response. The three verbs are applied to the `falcon policies` command to specify what you would like to do with policies, and a command line switch is used to specify the policy type to work with. Exported policies are written to disk as JSON with some Falcon Toolkit-specific data needed to import a policy back again.
@@ -444,4 +478,3 @@ Furthermore, GitHub Discussions provide the community with means to communicate.
 *Security issues should be raised to our [Security team](mailto:security@crowdstrike.com) and [Chris Hammond](mailto:Chris.Hammond@crowdstrike.com).*
 
 Thank you for using the Falcon Toolkit! We hope it is as useful to the Falcon user community as it is to us.
-

{falcon_toolkit-3.3.0 → falcon_toolkit-3.4.0}/falcon_toolkit/common/auth_backends/public_mssp.py

@@ -5,17 +5,16 @@ user which child CID to authenticate against.
 """
 import os
 
-from typing import Dict, List, Optional
+from typing import Dict, Optional
 
 import keyring
-import pick
 
 from caracara import Client
 
 from falcon_toolkit.common.auth import AuthBackend
 from falcon_toolkit.common.auth_backends.utils import advanced_options_wizard
 from falcon_toolkit.common.constants import KEYRING_SERVICE_NAME
-from falcon_toolkit.common.utils import fancy_input
+from falcon_toolkit.common.utils import fancy_input, choose_cid
 
 
 class PublicCloudFlightControlParentCIDBackend(AuthBackend):
@@ -118,16 +117,10 @@ class PublicCloudFlightControlParentCIDBackend(AuthBackend):
             )[chosen_cid_str]
         else:
             child_cids_data = parent_client.flight_control.get_child_cid_data(cids=child_cids)
-
-            options: List[pick.Option] = []
-            for child_cid_str, child_cid_data in child_cids_data.items():
-                child_cid_name = child_cid_data['name']
-                option_text = f"{child_cid_str}: {child_cid_name}"
-                option = pick.Option(label=option_text, value=child_cid_str)
-                options.append(option)
-
-            chosen_option, _ = pick.pick(options, "Please select a CID to connect to")
-            chosen_cid_str = chosen_option.value
+            chosen_cid_str = choose_cid(
+                cids=child_cids_data,
+                prompt_text="MSSP Child CID Search"
+            )
             chosen_cid = child_cids_data[chosen_cid_str]
 
         chosen_cid_name = chosen_cid['name']

{falcon_toolkit-3.3.0 → falcon_toolkit-3.4.0}/falcon_toolkit/common/auth_backends/utils.py

@@ -5,16 +5,17 @@ provide out of the box, as well as any that developers may write in the future.
 designed to avoid excessive code-reuse between similar implementations of auth backend.
 This file provides:
 - A list of all public CrowdStrike clouds
-- A cloud selection function to allow a user to choose a cloud via pick
+- A cloud selection function to allow a user to choose a cloud via Prompt Toolkit
 - Advanced options configuration for overriding cloud, TLS validation, etc.
 """
 from typing import (
     Dict,
     List,
     NamedTuple,
+    Tuple,
 )
 
-import pick
+from caracara.common.csdialog import csradiolist_dialog
 
 from falcon_toolkit.common.utils import fancy_input
 
@@ -29,13 +30,17 @@ CLOUDS = {
 
 
 def cloud_choice() -> str:
-    """Configure a selection of clouds and allow the user to choose one via pick."""
-    cloud_choices: List[pick.Option] = []
+    """Configure a selection of clouds and allow the user to choose one via Prompt Toolkit."""
+    cloud_choices: List[Tuple] = []
     for cloud_id, cloud_description in CLOUDS.items():
-        cloud_choices.append(pick.Option(cloud_description, cloud_id))
+        cloud_choices.append((cloud_id, cloud_description))
 
-    chosen_option, _ = pick.pick(cloud_choices, title="Please choose a Falcon cloud")
-    chosen_falcon_cloud: str = chosen_option.value
+    chosen_falcon_cloud: str = csradiolist_dialog(
+        title="Falcon Cloud Selection",
+        text="Please choose a Falcon cloud",
+        cancel_text=None,
+        values=cloud_choices,
+    ).run()
 
     return chosen_falcon_cloud
 
@@ -56,12 +61,16 @@ def advanced_options_wizard() -> AdvancedOptionsType:
 
     cloud_name = cloud_choice()
 
-    tls_verify_options: List[pick.Option] = [
-        pick.Option("Verify SSL/TLS certificates (recommended!)", value=True),
-        pick.Option("Do not verify SSL/TLS certificates (not recommended)", False),
+    tls_verify_options = [
+        (True, "Verify SSL/TLS certificates (recommended!)"),
+        (False, "Do not verify SSL/TLS certificates (not recommended)"),
     ]
-    chosen_ssl_verify, _ = pick.pick(tls_verify_options, title="Verify SSL/TLS certificates?")
-    ssl_verify: bool = chosen_ssl_verify.value
+    ssl_verify: bool = csradiolist_dialog(
+        title="Connection Security",
+        text="Enable SSL/TLS certificate verification?",
+        cancel_text=None,
+        values=tls_verify_options,
+    ).run()
 
     proxy_dict = None
     proxy_url_input = fancy_input("HTTPS proxy URL (leave blank if not needed): ", loop=False)

falcon_toolkit-3.4.0/falcon_toolkit/common/utils.py

@@ -0,0 +1,113 @@
+"""Falcon Toolkit: Common Utils.
+
+This file is a catch-all for small code snippets that can be shared across the various sub-modules
+of the application.
+"""
+import os
+
+from typing import Dict, Iterable
+
+from colorama import (
+    Fore,
+    Style,
+)
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import CompleteEvent, Completer, Completion
+from prompt_toolkit.document import Document
+
+from falcon_toolkit.common.constants import LOG_SUB_DIR
+
+
+def fancy_input(prompt_text: str, loop: bool = True):
+    """Request user input (with colour). Optionally loop until the input is not blank."""
+    inputted = False
+    colour_prompt = Style.BRIGHT + Fore.BLUE + \
+        prompt_text + Fore.RESET + Style.RESET_ALL
+
+    while not inputted:
+        data = input(colour_prompt)
+        if data or not loop:
+            inputted = True
+
+    return data
+
+
+def fancy_input_int(prompt_text: str) -> int:
+    """Request an integer from the user (with colour), and loop until the input is valid."""
+    valid_input = False
+    while not valid_input:
+        typed_input = fancy_input(prompt_text, loop=True)
+        if typed_input.isdigit():
+            valid_input = True
+
+    return int(typed_input)
+
+
+def configure_data_dir(config_dir: str):
+    """Configure the Falcon Toolkit data directory with a directory skeleton."""
+    if os.path.exists(config_dir):
+        if not os.path.isdir(config_dir):
+            raise ValueError("Specified configuration directory path is already a file")
+    else:
+        os.makedirs(config_dir)
+
+    logs_path = os.path.join(config_dir, LOG_SUB_DIR)
+    if not os.path.exists(logs_path):
+        os.makedirs(logs_path)
+
+
+def filename_safe_string(unsafe_string: str) -> str:
+    """Convert an unsafe string to one that can be included in a filename.
+
+    This function is heavily inspired by https://stackoverflow.com/a/7406369.
+    """
+    safe_string = "".join(
+        [c for c in unsafe_string if c.isalpha() or c.isdigit() or c == ' ']
+    ).rstrip()
+
+    # Replace spaces with underscores to match the general format of the log filename
+    clean_string = safe_string.replace(' ', '_')
+
+    return clean_string
+
+
+class CIDCompleter(Completer):
+    """Prompt Toolkit Completer that provides a searchable list of CIDs."""
+
+    def __init__(self, data_dict: Dict[str, Dict]):
+        """Create a new CID completer based on a dictionary that maps CIDs to meta strings."""
+        self.data_dict = data_dict
+
+    def get_completions(
+        self,
+        document: Document,
+        complete_event: CompleteEvent,
+    ) -> Iterable[Completion]:
+        """Yield CIDs that match the entered search string."""
+        for cid, cid_data in self.data_dict.items():
+            cid_name = cid_data["name"]
+            cloud_name = cid_data.get("cloud_name")
+            if cloud_name:
+                display_meta = f"{cid_name} [{cloud_name}]"
+            else:
+                display_meta = cid_name
+
+            word_lower = document.current_line.lower()
+            if word_lower in cid or word_lower in display_meta.lower():
+                yield Completion(
+                    cid,
+                    start_position=-len(document.current_line),
+                    display=cid,
+                    display_meta=display_meta,
+                )
+
+
+def choose_cid(cids: Dict[str, Dict], prompt_text="CID Search") -> str:
+    """Choose a CID from a dictionary of CIDs via Prompt Toolkit and return the CID string."""
+    cid_completer = CIDCompleter(data_dict=cids)
+    chosen_cid = None
+    while chosen_cid not in cids:
+        chosen_cid = prompt(f"{prompt_text} >", completer=cid_completer)
+
+    print(chosen_cid)
+    return chosen_cid

falcon_toolkit-3.4.0/falcon_toolkit/containment/__init__.py

@@ -0,0 +1,4 @@
+"""Falcon Toolkit: Host Containment.
+
+This sub-module contains the implementation of the falcon containment commands.
+"""