How to Set Up Custom Flags Using Spyctl CLI

How to Set Up Custom Detections Using Spyctl CLI

Setting up custom detections using the Spyctl CLI is straightforward. Before you start, ensure you have the Spyctl CLI installed and your organization set as a Spyctl context. You can follow the guide here for more details.

The Spyctl CLI supports various operations for custom flags (also known as custom detections), including creating, editing, deleting, disabling, and enabling. In this section, we'll go through these operations one by one.

1. Create a Custom Detection

The create command for custom flags allow you to create a custom detection using Spyderbat Query Language (SpyQL) in Spyctl CLI. Spyctl provides help options (--help) to guide you for every command. To view the help for creating a custom flag, run:

$ spyctl create custom-flag --help
Create a custom flag from a saved query.

This command allows you to write custom detections using the Spyderbat Query
Language (SpyQL).

At a minimum you must provide the following:
- schema
- query
- description
- severity
- name

To view available schema options run:
  'spyctl search --describe'
To view available query fields for your schema run:
  'spyctl search --describe <schema>'
Query operators are described here:
  https://docs.spyderbat.com/reference/search/search-operators

Example:
spyctl create custom-flag --schema Process --query "interactive = true and container_uid ~= '*'" --description "Detects interactive processes in containers" --severity high interactive-container-process

Options:
  -o, --output [yaml|json|ndjson|default]
  -a, --apply                     Apply the custom flag during creation.
  -d, --description               A description explaining what the flag
                                  detects.  [required]
  -q, --query                     Objects matching this query + schema
                                  combination will be flagged. If used, this
                                  will create a saved query.
  -s, --schema                    The schema for the SpyQL query used by the
                                  custom flag. If used, this will create a
                                  saved query.
  -Q, --saved-query               The UID of a previously saved query. If
                                  used, this will override the query and
                                  schema options.
  -t, --type                      The type of the custom flag. One of
                                  ['redflag', 'opsflag'].
  -S, --severity                  The severity of the custom flag. One of
                                  ['critical', 'high', 'medium', 'low',
                                  'info'].  [required]
  -D, --disable                   Disable the custom flag on creation.
  -T, --tags                      The tags associated with the custom flag.
                                  Comma delimited.
  -i, --impact                    The impact of the custom flag on the
                                  organization.
  -c, --content                   Markdown content describing extra details
                                  about the custom flag.
  -N, --saved_query_name          If a new saved query needs to be created,
                                  this overrides the auto-generated name.
  -y, --yes                       Automatically answer yes to all prompts.

Usage:
  spyctl create custom-flag [OPTIONS] NAME

To start, you must select the object you want to generate a flag for. This is done via the --schema option. You can view the list of available search schemas with the spyctl search --describe command.

Next you will want to craft a query for the schema you just selected. Each schema has a number of searchable fields, you can view them with Spyctl using the spyctl search --describe SCHEMA command. For example: spyctl search --describe Process or spyctl search --describe model_process both will retrieve the same results.

Using the above information let's create a simple custom flag for a K8s ReplicaSet having more than 6 replica instances:

$ spyctl create custom-flag replica-flag --schema "Replicaset" --query "spec.replicas > 6" -t "redflag" --severity "high" --description "A ReplicaSet running more than 6 replicas found"

Explanation:

• replica-flag - The name of the custom flag.

• --schema "Replicaset" - The schema used for the custom flag. To view available schemas/objects for creating custom flags, run $ spyctl search. The list includes processes, connections, all Kubernetes resource schemas, and more. You can also use model_k8s_replicaset for this option.

  • Note: Custom flags cannot be created for event_deviation, event_opsflag, event_redflag, or model_spydertrace Schemas.

• --query "spec.replicas > 6" - The SpyQL query used for the custom flag. The suggested method is to utilize the search functionality in the UI under the Search Section to identify and test the queries you want to flag. Once identified, you can copy and paste the query as a value for the -q option.

• --type "redflag" - The type of the custom flag. By default, the flag type is set to redflag

• --severity "high"- Specifies the perceived severity level of the flag.

• --description "A ReplicaSet running more than 6 replicas found" - A description of the custom flag.

You can also include other options like --content and --impact for the custom flag. These will show up in the console during an investigation. The YAML configuration generated by the create command will look like the example below. Verify the yaml before applying.

apiVersion: spyderbat/v1
kind: SpyderbatCustomFlag
metadata:
  name: replica-flag
  schema: model_k8s_replicaset
spec:
  enabled: true
  query: spec.replicas > 6
  flagSettings:
    type: redflag
    description: A ReplicaSet running more than 5 replicas found
    severity: high

This step only generates the YAML. The next step is to apply this flag.

To apply the custom flag, you have two options:

a. Apply Immediately: Run the same command as above and include the --apply flag to apply the flag immediately.

b. Apply from a File: Save the YAML configuration to a file and then apply it using following command: spyctl apply -f FILENAME

You should get "Successfully applied new custom flag with uid: flag:"* after applying the flag. Once set up, custom flags operate in real-time, triggering immediate flag as the query is met.

2. Get All Custom Flags

To retrieve all custom flags that were created, use the following command:

$ spyctl get custom-flags

You'll see a list of custom flags like this:

Getting custom-flags
Page 1/1
NAME                 UID       DESCRIPTION                                         SEVERITY      SCHEMA                     STATUS    AGE
replica-flag         flag:*    A ReplicaSet running more than 8 replicas found     high          model_k8s_replicaset       ENABLED   20m

3. Edit a Custom Flag

You can edit a custom flag if required using the below command, by passing the flag ID or name.

$ spyctl edit custom-flag <NAME_OR_ID>

After editing the yaml and saving it, you should see:

Successfully edited custom flag with uid: flag:*

4. Delete a Custom Flag

To remove custom flags that are no longer needed, use the below command:

$ spyctl delete custom-flag <NAME_OR_ID>

5. Disable a Custom Flag

To temporarily turn off a custom flag without deleting it, use:

$ spyctl disable custom-flag <NAME_OR_ID>

6. Enable a Custom Flag

If you need to re-enable a custom flag that has been disabled, use:

$ spyctl enable custom-flag NAME_OR_ID.