Skip to content

cs-shadowbq/crowdstrike-actors-list

BranchesTags

Repository files navigation

CrowdStrike Counter Adversary Operations(CAO) - Actors List

Version Python

This script is a simple Python script that uses the FalconPy SDK to list CrowdStrike Counter Adversary Operations(CAO) Actors. The script can be used to list all actors, targeted actors, or actors with a specific name. The script can also be combined with jq to filter and format the output.

Important

This script requires a CrowdStrike Falcon account with access to the CAO module and appropriate API permissions.

A primary use case for this script is to build a list of actors and their origins for in json format for further processing as tags in other systems.

usage: actorslist.py [-h] [-f FIND] [-k CLIENT_ID] [-s CLIENT_SECRET] [-c CLIENT_CLOUD] [-r] [-a] [-v] [-tf TABLE_FORMAT] [-o OUTPUT_PREFIX]

 _______                        __ _______ __        __ __
|   _   .----.-----.--.--.--.--|  |   _   |  |_.----|__|  |--.-----.
|.  1___|   _|  _  |  |  |  |  _  |   1___|   _|   _|  |    <|  -__|
|.  |___|__| |_____|________|_____|____   |____|__| |__|__|__|_____|
|:  1   |                         |:  1   |
|::.. . |                         |::.. . |   Falcon CAO
`-------'                         `-------'

ActorsList v1.2

Searches Falcon CAO for actor names matching a specified string.

If only one result is returned for a category, full details
for the record are displayed.

options:
  -h, --help            show this help message and exit
  -r, --reverse         Reverse the sort. (default: False)
  -a, --show_inactive   Include inactive actors as well as active actors. (default: False)
  -i, --only_inactive   Show only inactive actors. (default: False)
  -v, --verbose         Show additional actor details in output (actor type, motivations, capabilities, etc.). (default: False)
  -tf TABLE_FORMAT, --table_format TABLE_FORMAT
                        Set the table format(use tabulate forms, csv, or json). (default: fancy_grid)
  -o OUTPUT_PREFIX, --output_prefix OUTPUT_PREFIX
                        Save output with a filename prefix (table_format must be: csv or json). (default: None)

required arguments:
  -f FIND, --find FIND  Search string to identify. (default: *)
  -k CLIENT_ID, --client_id CLIENT_ID
                        CrowdStrike API client ID. Can be set via CLIENT_ID environment variable. (default: fb037e7f55c949888aed905920e07453)
  -s CLIENT_SECRET, --client_secret CLIENT_SECRET
                        CrowdStrike API client secret. Can be set via CLIENT_SECRET environment variable. (default: bOV4Aj2DTe90H1GarCs8iWQNE6XL3SocyxhU5f7v)
  -c CLIENT_CLOUD, --client_cloud CLIENT_CLOUD
                        CrowdStrike Cloud Region ['auto', 'us1', 'us2', 'eu1', 'usgov1', 'usgov2']. Can be set via CLIENT_CLOUD environment variable. (default: auto)

For a list of table formats check this page: https://github.com/astanin/python-tabulate#table-format

Configuration

Environment Variables

The script supports configuration via environment variables or a .env file. This makes it easy to avoid passing credentials on the command line.

ENV_PREFIX Configuration:

  • By default, the script uses FALCON_ as a prefix for environment variables
  • You can modify the ENV_PREFIX constant at the top of the script to use a different prefix or no prefix at all
  • Default prefix: ENV_PREFIX = "FALCON_"

Supported Environment Variables:

  • FALCON_CLIENT_ID - Your CrowdStrike API Client ID
  • FALCON_CLIENT_SECRET - Your CrowdStrike API Client Secret
  • FALCON_CLIENT_CLOUD - CrowdStrike Cloud Region (auto, us1, us2, eu1, usgov1, usgov2)

Using a .env file:

  1. Copy the example file:

    cp .env.example .env

  2. Edit .env and add your credentials:

    FALCON_CLIENT_ID=your_client_id_here
FALCON_CLIENT_SECRET=your_client_secret_here
FALCON_CLIENT_CLOUD=auto

  3. Run the script without CLI arguments:

    python3 actorslist.py -f spider

Using shell environment variables:

export FALCON_CLIENT_ID=your_client_id_here
export FALCON_CLIENT_SECRET=your_client_secret_here
export FALCON_CLIENT_CLOUD=auto
python3 actorslist.py -f spider

Priority Order:

  1. Command-line arguments (highest priority)
  2. Environment variables from .env file or shell
  3. Default values

Basic usage

Search for all active actor names containing the string spider.

python3 actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f spider

Providing a file prefix with the -o argument will also output the results in CSV format to individual files.

python3 actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f spider -o example -t csv
(writes .\example_actors.csv)

Result

Searching Falcon CAO for spider.
Retrieving XX actor results.

 _______ _______ _______  _____   ______ _______
 |_____| |          |    |     | |_____/ |______
 |     | |_____     |    |_____| |    \_ ______|

╒════════════════════╤══════════════════════════════════════════════════╤════════════╕
│ Name               │ Origins                                          │ ID         │
╞════════════════════╪══════════════════════════════════════════════════╪════════════╡
│ X SPIDER           │                                                  │ ADV-111111 │
├────────────────────┼──────────────────────────────────────────────────┼────────────┤
│ Y SPIDER           │                                                  │ ADV-222222 │
├────────────────────┼──────────────────────────────────────────────────┼────────────┤
│ Z SPIDER           │ Location 1                                       │ ADV-333333 │
├────────────────────┼──────────────────────────────────────────────────┼────────────┤
│ XX SPIDER          │ Location 1                                       │ ADV-444444 │
├────────────────────┼──────────────────────────────────────────────────┼────────────┤
│ XY SPIDER          │                                                  │ ADV-555555 │
├────────────────────┼──────────────────────────────────────────────────┼────────────┤
│ etc.. SPIDER       │ Location 1, Location 2                           │ ADV-999999 │
╘════════════════════╧══════════════════════════════════════════════════╧════════════╛

Filtering by Actor Status

By default, the script returns only active actors. You can control this behavior with status flags:

Show only active actors (default)

python3 actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f spider

Show both active and inactive actors

python3 actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f spider -a

Show only inactive actors

python3 actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f spider -i

Include status column in CSV output

When outputting to CSV format, the Status column is automatically included:

python3 actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f spider -tf csv -a
"Name","Origins","Status","ID"
"SPIDER ONE","Russian Federation","Active","ADV-123456"
"SPIDER TWO","","Inactive","ADV-789012"

With verbose mode, the Status column appears alongside other detailed fields:

python3 actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f spider -tf csv -v -a -o output
(writes ./output_actors.csv with Status column included)

Listing Actor Groups with JQ formatting

List know Actors. (-a flag for all actors)

python3 ./actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -t json -a | jq length
240

Search for active actors list, show the count of the actors. (array size of 142)

python3 ./actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -t json | jq length
142

Search for active actors list with targeted actors, show the count of the actors. (array size of 85)

python3 ./actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -t json | jq 'map(select( .actor_type == "targeted"))|length'
85

Search for active actors named PANDA in the actor list with targeted actors. Return the original JSON object array of the actors. (array size of 30)

 python3 ./actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -t json -f "PANDA" | jq 'map(select( .actor_type == "targeted"))'
[{ "id": 193585,
    "name": "XXXXX PANDA",
    "slug": "xxxxx-panda",
    "actor_type": "targeted",
    "url": ...
  }, {...}
]

Search for active actors named PANDA in the actor list with alternative names that include Typhoon (Microsoft named actors). Return the count of the actors. (array size of 10) (https://learn.microsoft.com/en-us/defender-xdr/microsoft-threat-actor-naming)

python3 ./actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -t json -f "PANDA" | jq 'map(select( .known_as |contains ("Typhoon")))|length'
10

Building a JSON Object for tags in other systems

More complex query, search for active actors named BEAR in the actor list with targeted actors. Return a new JSON object array of the actors, with the actor's name and Country origin array (sometimes > 1).

python3 ./actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -t json -f "BEAR" | jq 'map(select( .actor_type == "targeted"))|map ({ name:.name, origins: [.origins[].value]   })'

[
  {
    "name": "XXXXXXX BEAR",
    "origins": [
      "Russian Federation"
    ]
  },
  {
    "name": "YYYY BEAR",
    "origins": [
      "Russian Federation"
    ]
  },
...
  {
    "name": "ZZZZZZZZZ BEAR",
    "origins": [
      "Russian Federation"
    ]
  },
  {
    "name": "AAAAAAAA BEAR",
    "origins": [
      "Russian Federation"
    ]
  },
  {
    "name": "BBBBBB BEAR",
    "origins": [
      "Russian Federation"
    ]
  }

Detailed Actor Information

Search for a specific actor. (Any time only one result is returned, the application defaults to a detailed display.)

python3 actorslist.py -k $FALCON_CLIENT_ID -s $FALCON_CLIENT_SECRET -f "fancy bear"

Results

Searching Falcon CAO for fancy bear.
Retrieving 1 actor results.
 _______                             ______
|    ___|.---.-.-----.----.--.--.   |   __ \.-----.---.-.----.
|    ___||  _  |     |  __|  |  |   |   __ <|  -__|  _  |   _|
|___|    |___._|__|__|____|___  |   |______/|_____|___._|__|
                          |_____|

First activity: mm-dd-YYYY     Most recent activity: mm-dd-YYYY

Otherwise known as
List of actor aliases and personas

Adversary description
FANCY BEAR is an adversary attributed to the lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Iaculis nunc sed augue
lacus viverra vitae congue eu consequat. Sem nulla pharetra diam sit amet nisl suscipit. Sed id
semper risus in hendrerit gravida rutrum. Odio ut sem nulla pharetra diam sit amet nisl suscipit.
At imperdiet dui accumsan sit amet nulla. At in tellus integer feugiat scelerisque varius. Sem et
tortor consequat id porta nibh venenatis. Scelerisque eu ultrices vitae auctor eu augue ut lectus
arcu. Risus ultricies tristique nulla aliquet enim. Sit amet dictum sit amet justo donec enim diam
vulputate. Parturient montes nascetur ridiculus mus mauris vitae ultricies leo. Commodo nulla 
facilisi nullam vehicula ipsum a arcu. Quam elementum pulvinar etiam non quam. Vitae ultricies leo 
integer malesuada nunc. Ornare arcu odio ut sem nulla pharetra diam.

Sodales ut etiam sit amet nisl purus in mollis nunc. Tellus rutrum tellus pellentesque eu tincidunt 
tortor aliquam nulla facilisi. Libero id faucibus nisl tincidunt eget. Pharetra magna ac placerat 
vestibulum lectus mauris. Enim sit amet venenatis urna cursus eget nunc. Sagittis purus sit amet 
volutpat consequat mauris nunc. Enim nec dui nunc mattis enim ut tellus elementum sagittis. Massa 
eget egestas purus viverra accumsan in nisl. Egestas sed tempus urna et. Tincidunt vitae semper quis 
lectus nulla at. At urna condimentum mattis pellentesque id. Massa tincidunt nunc pulvinar sapien et 
ligula. Aliquam vestibulum morbi blandit cursus risus at ultrices mi. Et leo duis ut diam quam nulla 
porttitor. Ut placerat orci nulla pellentesque. Id diam maecenas ultricies mi. Sagittis eu volutpat 
odio facilisis mauris.

Actor type: Actor Type     Capability: Actor Capability     Origins: Actor Origin

Motivations: Motivation detail

Objectives: Objective list

Targeted regions: List of targeted regions

Targeted countries
List of targeted countries

Targeted industries
List of targeted industries

Tactics, Techniques and Procedures
Actions and Objectives: Action and Objectives detail

Command and Control: Command and Control detail

Delivery: Delivery detail

Exploitation: List of exploited CVEs

Installation: Installation detail

Reconnaissance: Reconnaissance detail

Weaponization: Weaponization detail

Total actors: 1
Execution time: 1.10 seconds

Dependencies

FalconPy

Falconpy is the supported CrowdStrike Python Falcon SDK.

Tabluate

Tabulate is a Python library that can be used to format the output of the actors list.

JQ

JQ is a lightweight and flexible command-line JSON processor. It can be used to filter and format the output of the actors list.

TermColor

TermColor is a Python library that can be used to colorize the output of the actors list.

Installation

pip install -r requirements.txt

References

About

Python script to list CrowdStrike actors.

Topics

cao crowdstrike falconpy

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 1

v1.2 Latest
Feb 2, 2026

Contributors

Languages