falcon-toolkit 3.4.2__tar.gz → 3.5.1__tar.gz

{falcon_toolkit-3.4.2 → falcon_toolkit-3.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: falcon-toolkit
-Version: 3.4.2
+Version: 3.5.1
 Summary: Toolkit to interface with CrowdStrike Falcon via the API
 Home-page: http://github.com/CrowdStrike/Falcon-Toolkit
 License: MIT
@@ -18,11 +18,12 @@ 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.13
 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: caracara (>=0.9.0,<0.10.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)
@@ -31,7 +32,6 @@ 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
@@ -221,19 +221,22 @@ 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)  | `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 |
+| &darr; API Scopes // Commands &rarr; |              `host_search`               |                 `shell`                  |        `policies`<br>(Prevention)        |         `policies`<br>(Response)         | `containment`<br>Host Containment | `maintenance_token`<br>Maintenance Tokens |                     `users`<br>User Management                     |
+| ------------------------------------ | :--------------------------------------: | :--------------------------------------: | :--------------------------------------: | :--------------------------------------: | :-------------------------------: | :---------------------------------------: | :----------------------------------------------------------------: |
+| **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                     |                                                                    |
+| **Sensor Download: Read**            |                                          |                                          |                                          |                                          |                                   |                                           |               X<br>*For adding roles to users only*                |
+| **User Management: Read**            |                                          |                                          |                                          |                                          |                                   |                                           |           X<br>*For `describe` and `list` sub-commands*            |
+| **User Management: Write**           |                                          |                                          |                                          |                                          |                                   |                                           | X<br>*For user and user role add, import, and change sub-commands* |
 
 ### Showing Your Profiles
 
@@ -505,6 +508,29 @@ $ falcon policies -p import MyExportedPolicy.json
 ...
 ```
 
+## User Manipulation
+
+The `falcon users` command has multiple sub-commands that let you view and manipulate users in your Falcon tenant.
+- `add_user`: Add a new user.
+- `add_roles`: Assign new roles to a user.
+- `delete_user`: Delete a user.
+- `describe_users`: Show all users in a Falcon tenant alongside their roles.
+- `import_users`: Import a list of users from a CSV.
+- `list_roles`: Show all roles that may be assigned to users.
+
+### CSV Formatting for `import_users`
+
+The CSV must contain the header first_name,last_name,email_address, and optionally may contain the roles field.
+
+first_name,last_name,email_address,roles
+alice,example,alice.example@example.com
+bob,example,bob.example@example.com,risk_manager
+eve,example,eve.example@example.com
+
+```shell
+$ falcon users import_users NewUsers.csv
+```
+
 ## Support & Community Forums
 
 Falcon Toolkit is an open source project, and not a formal CrowdStrike product, designed to assist users with managing their Falcon tenants and executing commands at scale. As such, it carries no formal support, express or implied. This project originated out of the CrowdStrike Services Incident Response (IR) team's need to execute commands across Falcon tenants quickly, at scale, and with auditing, and is maintained by [Chris Hammond](mailto:Chris.Hammond@crowdstrike.com).

{falcon_toolkit-3.4.2 → falcon_toolkit-3.5.1}/README.md

@@ -183,19 +183,22 @@ 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)  | `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 |
+| &darr; API Scopes // Commands &rarr; |              `host_search`               |                 `shell`                  |        `policies`<br>(Prevention)        |         `policies`<br>(Response)         | `containment`<br>Host Containment | `maintenance_token`<br>Maintenance Tokens |                     `users`<br>User Management                     |
+| ------------------------------------ | :--------------------------------------: | :--------------------------------------: | :--------------------------------------: | :--------------------------------------: | :-------------------------------: | :---------------------------------------: | :----------------------------------------------------------------: |
+| **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                     |                                                                    |
+| **Sensor Download: Read**            |                                          |                                          |                                          |                                          |                                   |                                           |               X<br>*For adding roles to users only*                |
+| **User Management: Read**            |                                          |                                          |                                          |                                          |                                   |                                           |           X<br>*For `describe` and `list` sub-commands*            |
+| **User Management: Write**           |                                          |                                          |                                          |                                          |                                   |                                           | X<br>*For user and user role add, import, and change sub-commands* |
 
 ### Showing Your Profiles
 
@@ -467,6 +470,29 @@ $ falcon policies -p import MyExportedPolicy.json
 ...
 ```
 
+## User Manipulation
+
+The `falcon users` command has multiple sub-commands that let you view and manipulate users in your Falcon tenant.
+- `add_user`: Add a new user.
+- `add_roles`: Assign new roles to a user.
+- `delete_user`: Delete a user.
+- `describe_users`: Show all users in a Falcon tenant alongside their roles.
+- `import_users`: Import a list of users from a CSV.
+- `list_roles`: Show all roles that may be assigned to users.
+
+### CSV Formatting for `import_users`
+
+The CSV must contain the header first_name,last_name,email_address, and optionally may contain the roles field.
+
+first_name,last_name,email_address,roles
+alice,example,alice.example@example.com
+bob,example,bob.example@example.com,risk_manager
+eve,example,eve.example@example.com
+
+```shell
+$ falcon users import_users NewUsers.csv
+```
+
 ## Support & Community Forums
 
 Falcon Toolkit is an open source project, and not a formal CrowdStrike product, designed to assist users with managing their Falcon tenants and executing commands at scale. As such, it carries no formal support, express or implied. This project originated out of the CrowdStrike Services Incident Response (IR) team's need to execute commands across Falcon tenants quickly, at scale, and with auditing, and is maintained by [Chris Hammond](mailto:Chris.Hammond@crowdstrike.com).

falcon_toolkit-3.5.1/falcon_toolkit/common/meta.py

@@ -0,0 +1,11 @@
+"""Falcon Toolkit: Meta.
+
+This is where all functions and variable setting that are based on application metadata live.
+"""
+
+import importlib.metadata
+
+# Derive the version via importlib.metadata, which is populated based on the version in
+# pyproject.toml. We used to use pkg_resources for this, but using importlib.metadata means
+# that setuptools is no longer required.
+__version__ = importlib.metadata.version("falcon-toolkit")

{falcon_toolkit-3.4.2 → falcon_toolkit-3.5.1}/falcon_toolkit/falcon.py

@@ -48,12 +48,14 @@ from falcon_toolkit.common.constants import (
     OLD_DEFAULT_CONFIG_DIR,
 )
 from falcon_toolkit.common.logging_config import configure_logger
+from falcon_toolkit.common.meta import __version__
 from falcon_toolkit.common.utils import configure_data_dir
 from falcon_toolkit.containment.cli import cli_containment
 from falcon_toolkit.hosts.cli import cli_host_search
 from falcon_toolkit.maintenance_token.cli import cli_maintenance_token
 from falcon_toolkit.policies.cli import cli_policies
 from falcon_toolkit.shell.cli import cli_shell
+from falcon_toolkit.users.cli import cli_users
 
 
 @click.group()
@@ -134,7 +136,10 @@ def cli(
 
     # Configure context that can be passed down to other options
     ctx.ensure_object(dict)
-    click.echo(click.style("Falcon Toolkit", fg="blue", bold=True))
+    click.echo(
+        click.style("Falcon Toolkit", fg="blue", bold=True)
+        + click.style(f" v{__version__}", fg="black", bold=True)
+    )
     hyperlink = build_file_hyperlink(config_path, config_path, "falcon_config_path")
     click.echo(click.style(f"Configuration Directory: {hyperlink}", fg="black"))
     if verbose:
@@ -312,3 +317,4 @@ cli.add_command(cli_list_filters)
 cli.add_command(cli_maintenance_token)
 cli.add_command(cli_policies)
 cli.add_command(cli_shell)
+cli.add_command(cli_users)

{falcon_toolkit-3.4.2 → falcon_toolkit-3.5.1}/falcon_toolkit/shell/cli.py

@@ -94,7 +94,7 @@ from falcon_toolkit.shell.prompt import RTRPrompt
     required=False,
     help="Set the timeout for RTR (default: 30s)",
 )
-def cli_shell(  # pylint: disable=too-many-arguments,too-many-locals
+def cli_shell(  # pylint: disable=too-many-arguments,too-many-locals,too-many-positional-arguments
     ctx: click.Context,
     device_id_list: str,
     device_id_file: str,

{falcon_toolkit-3.4.2 → falcon_toolkit-3.5.1}/falcon_toolkit/shell/prompt.py

@@ -49,6 +49,7 @@ class RTRPrompt(Cmd):
 
     # pylint: disable=too-many-arguments
     # pylint: disable=too-many-locals
+    # pylint: disable=too-many-positional-arguments
     # pylint: disable=too-many-statements
     def __init__(
         self,
@@ -388,6 +389,7 @@ class RTRPrompt(Cmd):
 
         return get_file_data
 
+    # pylint: disable=too-many-positional-arguments
     def write_result_row(self, command: str, aid: str, complete: bool, stdout: str, stderr: str):
         """Write a row of output to the CSV log file."""
         hostname = self.device_data[aid].get("hostname", "<NO HOSTNAME>")

falcon_toolkit-3.5.1/falcon_toolkit/users/__init__.py

@@ -0,0 +1,4 @@
+"""Falcon Toolkit: User Management.
+
+This sub-module contains the implementation of the falcon user management commands.
+"""

falcon_toolkit-3.5.1/falcon_toolkit/users/cli.py

@@ -0,0 +1,128 @@
+"""Falcon Toolkit: User Modification.
+
+This file contains the CLI options for the falcon user modification commands.
+"""
+
+from os import path
+
+import click
+from caracara import Client
+from prompt_toolkit import prompt
+
+from falcon_toolkit.users.user_management import (
+    user_deletion,
+    add_csv_users,
+    add_single_user,
+    add_roles_to_user,
+    print_formatted_user_roles,
+    describe_existing_users,
+)
+from falcon_toolkit.common.cli import get_instance
+
+
+@click.group(
+    name="users",
+    help="Manage Falcon User Creation and Deletion",
+)
+@click.pass_context
+def cli_users(ctx: click.Context):
+    """Falcon Toolkit user management base command."""
+    instance = get_instance(ctx)
+    client: Client = instance.auth_backend.authenticate(ctx)
+    ctx.obj["client"] = client
+
+
+@click.command(
+    name="add_user",
+    help="Create users via CLI inputs",
+)
+@click.pass_context
+def add_user(ctx: click.Context):
+    """Create a new user in the Falcon tenant."""
+    single_email = prompt("Enter the new user's email address: ")
+    first_name = prompt(f"Enter {single_email}'s first name: ")
+    last_name = prompt(f"Enter {single_email}'s last name: ")
+    add_single_user(ctx.obj["client"], first_name, last_name, single_email)
+
+
+@click.command(
+    name="import_users",
+    help="Create users from a CSV file formatted first_name,last_name,email_address",
+)
+@click.argument("csv_file")
+@click.pass_context
+def import_users(ctx: click.Context, csv_file):
+    """Create users and set their roles in the Falcon tenant from a CSV file."""
+    if path.isfile(csv_file):
+        add_csv_users(ctx.obj["client"], csv_file)
+    else:
+        click.echo(click.style("Error: Invalid File Path", bold=True, fg="red"))
+
+
+@click.command(
+    name="delete_user",
+    help="Delete users via email address",
+)
+@click.option(
+    "-f",
+    "--file",
+    "file_name",
+    help="path to line-seperated file of user accounts to be deleted",
+)
+@click.option(
+    "-e",
+    "--user_email",
+    help="Email address of user to be deleted",
+)
+@click.pass_context
+def delete_user(ctx: click.Context, file_name: str = None, user_email: str = None):
+    """Delete a user from the Falcon tenant by email address, or delete many using a file."""
+    email_list = []
+    if file_name is not None:
+        try:
+            with open(file_name, newline="", encoding="utf-8") as email_list_file:
+                email_list = email_list_file.read().splitlines()
+            user_deletion(ctx.obj["client"], email_list)
+        except FileNotFoundError:
+            click.echo(click.style("Error: Invalid File Path", bold=True, fg="red"))
+    elif user_email is not None:
+        email_list.append(user_email)
+        user_deletion(ctx.obj["client"], email_list)
+    else:
+        click.echo(
+            click.style(
+                "Please specify either a file or user email. "
+                "Try 'falcon users delete_user --help' for help.",
+                bold=True,
+                fg="red",
+            )
+        )
+
+
+@click.command(name="describe_users", help="List all existing users in the cloud instance")
+@click.pass_context
+def describe_users(ctx: click.Context):
+    """Show all the user accounts in the Falcon tenant, and their respective roles."""
+    describe_existing_users(ctx.obj["client"])
+
+
+@click.command(name="list_roles", help="List all available roles in the cloud instance")
+@click.pass_context
+def list_roles(ctx: click.Context):
+    """Show all the roles that exist within the Falcon tenant and may be assigned to users."""
+    print_formatted_user_roles(ctx.obj["client"])
+
+
+@click.command(name="add_roles", help="Add roles via user email and role ID")
+@click.pass_context
+def add_roles(ctx: click.Context):
+    """Grant new roles to a user account in the Falcon tenant."""
+    add_roles_to_user(ctx.obj["client"])
+
+
+cli_users.add_command(add_user)
+cli_users.add_command(import_users)
+cli_users.add_command(delete_user)
+cli_users.add_command(describe_users)
+cli_users.add_command(list_roles)
+cli_users.add_command(add_roles)

falcon_toolkit-3.5.1/falcon_toolkit/users/user_management.py

@@ -0,0 +1,278 @@
+"""Falcon Toolkit: User Management.
+
+This file contains the logic required to create and configure users.
+"""
+
+import csv
+import sys
+from operator import itemgetter
+from textwrap import TextWrapper
+from typing import Dict, List, Optional, Set, Union
+
+import click
+import click_spinner
+import tabulate
+from caracara import Client
+from caracara.common.csdialog import csradiolist_dialog
+from caracara.common.exceptions import GenericAPIError
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import FuzzyWordCompleter
+
+from falcon_toolkit.hosts import host_search
+
+
+def _tabulate_users(  # pylint: disable=R0914
+    user_data: Union[List[Dict[str, str]], Dict[str, str]],
+    role_data: Optional[Dict[str, Dict]] = None,
+) -> None:
+    """Pretty print a list of users to screen in a tabular format."""
+    header_row = [
+        click.style("Name", bold=True, fg="blue"),
+        click.style("Email Address", bold=True, fg="blue"),
+        click.style("Status", bold=True, fg="blue"),
+        click.style("Creation Date", bold=True, fg="blue"),
+        click.style("Modification Date", bold=True, fg="blue"),
+        click.style("UUID", bold=True, fg="blue"),
+        click.style("Roles", bold=True, fg="blue"),
+    ]
+    table_rows = []
+
+    grouping_tag_wrap = TextWrapper()
+    grouping_tag_wrap.width = 40
+
+    sixteen_wrap = TextWrapper()
+    sixteen_wrap.width = 16
+
+    for extracted_dict in user_data:
+        email_address = extracted_dict["uid"]
+        name = str(extracted_dict["first_name"]) + " " + str(extracted_dict["last_name"])
+        creation_date = extracted_dict["created_at"]
+        modification_date = extracted_dict["updated_at"]
+        uuid = extracted_dict["uuid"]
+        if role_data:
+            roles_list = sorted(
+                [
+                    role_data[x]["display_name"] if x in role_data else x
+                    for x in extracted_dict["roles"]
+                ]
+            )
+        else:
+            roles_list = extracted_dict["roles"]
+
+        activation_status = extracted_dict["status"]
+        if activation_status == "active":
+            status = click.style("Active", fg="green")
+        else:
+            status = click.style(activation_status, fg="red")
+
+        string_roles = ""
+        for role in roles_list:
+            string_roles = string_roles + role + "\n"
+
+        row = [name, email_address, status, creation_date, modification_date, uuid, string_roles]
+        table_rows.append(row)
+
+    table_rows = sorted(table_rows, key=itemgetter(1, 0))
+
+    for row in table_rows:
+        host_search.vertically_align_middle(row)
+
+    table_rows.insert(0, header_row)
+
+    click.echo(
+        tabulate.tabulate(
+            table_rows,
+            tablefmt="fancy_grid",
+        )
+    )
+
+
+def add_csv_users(client: Client, csv_name: str):  # pylint: disable=R0914
+    """Create users based on a CSV formatted first_name,last_name,email_address."""
+    successful_uuid_set: Set[str] = set()
+
+    with open(csv_name, newline="", encoding="utf-8") as csv_file:
+        reader = csv.DictReader(csv_file)
+        if (
+            "first_name" not in reader.fieldnames
+            or "last_name" not in reader.fieldnames
+            or "email_address" not in reader.fieldnames
+        ):
+            raise KeyError(
+                "The CSV must contain at least the fields first_name, last_name, and email_address"
+            )
+
+        for row in reader:
+            first_name = row["first_name"]
+            last_name = row["last_name"]
+            email_address = row["email_address"]
+            uuid: Optional[str] = None
+
+            click.echo(
+                "Processing user: "
+                + click.style(f"{first_name} {last_name}", bold=True)
+                + " ("
+                + click.style(email_address, bold=True)
+                + ")"
+            )
+
+            try:
+                user_add_result = client.users.add_user(
+                    first_name,
+                    last_name,
+                    email_address,
+                )
+                uuid = user_add_result["uuid"]
+                successful_uuid_set.add(uuid)
+
+            except GenericAPIError as bad_user_error:
+                print(click.style(bad_user_error, bold=True, fg="yellow"))
+            except KeyError:
+                print(click.style("The API response did not include a new user UUID", fg="red"))
+
+            if "roles" in row and row["roles"] is not None:
+                roles_str = row["roles"]
+                click.echo(f"Adding roles to user {email_address}: {roles_str}")
+
+                if not uuid:
+                    uuid = client.users.get_uuid_by_email(email_address)
+
+                roles = roles_str.split(",")
+                if client.users.add_user_roles(uuid, roles):
+                    successful_uuid_set.add(uuid)
+                else:
+                    print(click.style(f"Role addition failed for {roles}", bold=True, fg="red"))
+
+    if not successful_uuid_set:
+        # Nothing succeeded
+        return
+
+    with click_spinner.spinner():
+        user_data = client.users.describe_users(user_uuids=list(successful_uuid_set))
+        role_data = client.users.describe_available_roles()
+
+    click.echo(click.style("Affected Users", bold=True))
+    _tabulate_users(list(user_data.values()), role_data)
+
+
+def add_single_user(client: Client, first_name: str, last_name: str, email_address: str):
+    """Create a single user in the Falcon tenant."""
+    with click_spinner.spinner():
+        result = client.users.add_user(first_name, last_name, email_address)
+        user_data = client.users.describe_users(user_uuids=[result["uuid"]])
+
+    click.echo(click.style("New User", bold=True))
+    _tabulate_users(list(user_data.values()))
+
+
+def delete_user_guardrails(email_addresses: list):
+    """Confirm via a visual Prompt Toolkit box whether the user really wants to delete a user."""
+    confirmation_options = [
+        (False, "Abort"),
+        (True, "Delete accounts"),
+    ]
+    prompt_text = "Are you sure you want to delete these accounts?\n" + "\n".join(email_addresses)
+    confirmation: bool = csradiolist_dialog(
+        title="Confirm User Deletion Action",
+        text=prompt_text,
+        values=confirmation_options,
+    ).run()
+
+    if confirmation:
+        click.echo(click.style("User confirmed action", bold=True, fg="green"))
+        return True
+
+    click.echo(click.style("Aborted!", bold=True, fg="red"))
+    return False
+
+
+def user_deletion(client: Client, email_addresses: list):
+    """Validate email addresses, confirm deletion, and ultimately delete users."""
+    uuid_list = []
+    bad_emails = []
+    for i in email_addresses:
+        try:
+            uuid = client.users.get_uuid_by_email(i)
+            uuid_list.append(uuid)
+        except GenericAPIError:
+            click.echo(click.style(f"Invalid Email Address: {i}", bold=True, fg="red"))
+            bad_emails.append(i)
+
+    good_emails = [email for email in email_addresses if email not in bad_emails]
+    if good_emails and delete_user_guardrails(good_emails):
+        for i in uuid_list:
+            deletion_result = client.users.delete_user(i)
+            if deletion_result is False:
+                click.echo(click.style(f"Error deleting user: {i}", bold=True, fg="red"))
+
+
+def print_formatted_user_roles(client: Client):
+    """Retrieve all available user roles, and format them on screen."""
+    unformatted_roles = client.users.describe_available_roles()
+    for role_key in unformatted_roles:
+        all_values = unformatted_roles[role_key]
+        user_id = all_values["id"]
+        display_name = all_values["display_name"]
+        description = all_values["description"]
+        is_global = all_values["is_global"]
+        print(click.style(f"ID: {user_id}", bold=True, fg="green"))
+        print(f"Display Name: {display_name}")
+        print(f"Is Global: {is_global}")
+        print("Description:")
+        print(description)
+        print("")
+
+
+def add_roles_to_user(client: Client):
+    """Autocomplete role names to efficiently add roles to a user via email address.
+
+    Sensor Download READ permissions required.
+    """
+    try:
+        user_email = prompt("Enter the user email address: ")
+        user_uuid = client.users.get_uuid_by_email(user_email)
+    except GenericAPIError as error:
+        print(click.style(error, bold=True, fg="red"))
+        sys.exit()
+
+    selected_roles = []
+    all_roles = []
+    all_roles_meta_dict = {}
+
+    unformatted_roles = client.users.describe_available_roles()
+    for role_key in unformatted_roles:
+        all_values = unformatted_roles[role_key]
+        all_roles.append(all_values["id"])
+        all_roles_meta_dict[all_values["id"]] = all_values["display_name"]
+
+    list_completer = FuzzyWordCompleter(
+        all_roles,
+        meta_dict=all_roles_meta_dict,
+    )
+    add_more_roles = "yes"
+    while add_more_roles.lower() == "yes" or add_more_roles.lower() == "y":
+        role_option = prompt("Select Role: ", completer=list_completer)
+        selected_roles.append(role_option)
+        add_more_roles = prompt("Add more roles? (yes or no): ")
+
+    print(f"Adding selected roles: {selected_roles}")
+    actually_add = prompt("Continue? (yes or no): ")
+    if actually_add.lower() == "yes" or actually_add.lower() == "y":
+
+        result = client.users.add_user_roles(user_uuid, selected_roles)
+        if result is True:
+            print(click.style("Successfully added roles", bold=True, fg="green"))
+        else:
+            print(click.style("Operation Failed, Check Role Name", bold=True, fg="red"))
+    else:
+        print("Cancelling operation")
+
+
+def describe_existing_users(client: Client):
+    """Show all users in a CID within a formatted table."""
+    with click_spinner.spinner():
+        user_data = client.users.describe_users()
+        role_data = client.users.describe_available_roles()
+        formatted_data = list(user_data.values())
+
+    _tabulate_users(formatted_data, role_data)

{falcon_toolkit-3.4.2 → falcon_toolkit-3.5.1}/pyproject.toml

@@ -1,11 +1,12 @@
 [tool.poetry]
 name = "falcon-toolkit"
-version = "3.4.2"
+version = "3.5.1"
 description = "Toolkit to interface with CrowdStrike Falcon via the API"
 license = "MIT"
 authors = [
     "Chris Hammond <chris.hammond@crowdstrike.com>",
     "Kira Noël <kira.noel@crowdstrike.com>",
+    "Natalie Eckles <natalie.eckles@crowdstrike.com>",
 ]
 repository = "http://github.com/CrowdStrike/Falcon-Toolkit"
 readme = "README.md"
@@ -30,7 +31,7 @@ classifiers = [
 
 [tool.poetry.dependencies]
 python = "^3.9"
-caracara = "^0.7.0"
+caracara = "^0.9.0"
 click = "^8.1.3"
 click-option-group = "^0.5.6"
 click-spinner = "^0.1.10"
@@ -40,7 +41,6 @@ keyring = ">=24,<26"
 platformdirs = "^4.2.0"
 tabulate = "^0.9.0"
 prompt-toolkit = "^3.0.43"
-setuptools = "^69.0"
 
 [tool.poetry.scripts]
 falcon = "falcon_toolkit.falcon:cli"

falcon_toolkit-3.4.2/falcon_toolkit/common/meta.py

@@ -1,9 +0,0 @@
-"""Falcon Toolkit: Meta.
-
-This is where all functions and variable setting that are based on application metadata live.
-"""
-
-import pkg_resources
-
-# Derive the version via pkg_resources, which is populated based on the version in pyproject.toml
-__version__ = pkg_resources.get_distribution(__name__.split(".", maxsplit=1)[0]).version