Commands
spyctl
spyctl displays and controls resources within your Spyderbat environment
spyctl [OPTIONS] COMMAND [ARGS]...
apply
Apply a configuration to a resource by file name.
spyctl apply [OPTIONS]
Options
- -f, --filename <filename>
Required Filename containing Spyderbat resource.
Use “spyctl <command> –help” for more information about a given command.
config
Modify spyctl config files.
spyctl config [OPTIONS] COMMAND [ARGS]...
Use “spyctl <command> –help” for more information about a given command.
current-context
Display the current-context.
spyctl config current-context [OPTIONS]
Options
- -g, --global
When operating within a spyctl workspace, this displays the current context in the global configuration.
Use “spyctl <command> –help” for more information about a given command.
delete-apisecret
Delete the specified apisecret from a spyctl configuration file.
NAME is the name of the apisecret to delete.
spyctl config delete-apisecret [OPTIONS] NAME
Options
- -y, --yes, --assume-yes
Automatic yes to prompts; assume “yes” as answer to all prompts and run non-interactively.
Arguments
- NAME
Required argument
Use “spyctl <command> –help” for more information about a given command.
delete-context
Delete the specified context from a spyctl configuration file.
NAME is the name of the context to delete.
spyctl config delete-context [OPTIONS] NAME
Options
- -g, --global
When operating within a spyctl workspace, this deletes a context from the global spyctl configuration file.
- -y, --yes, --assume-yes
Automatic yes to prompts; assume “yes” as answer to all prompts and run non-interactively.
Arguments
- NAME
Required argument
Use “spyctl <command> –help” for more information about a given command.
get-apisecrets
Describe one or many apisecrets.
spyctl config get-apisecrets [OPTIONS] [NAME]
Options
- -o, --output <output>
- Options:
yaml | json | default | wide
Arguments
- NAME
Optional argument
Use “spyctl <command> –help” for more information about a given command.
get-contexts
Describe one or many contexts.
NAME is the name of a specific context to view.
The default behavior is to show all of the contexts accessible to the current working directory. If not using a workspace, this is only the contexts in the global config. See –help for “spyctl config init” for more details.
spyctl config get-contexts [OPTIONS] [NAME]
Options
- -o, --output <output>
- Options:
default | wide
- -g, --global
When operating within a spyctl workspace, this displays only contexts within the global spyctl configuration file.
- -w, --workspace
When operating within a spyctl workspace, this displays only contexts within the workspace configuration file.
Arguments
- NAME
Optional argument
Use “spyctl <command> –help” for more information about a given command.
init-workspace
Initialize a workspace.
This command creates a ‘.spyctl/config’ file in the current working directory. Workspaces are a spyctl configuration file local to a specific directory. They allow you to create contexts only accessible from the directory subtree from where the config file resides. They also allow you to set a current context for a directory subtree.
This is helpful if you’re working on a specific service or container and want spyctl to return data relevant only to that application.
For example:
If your cwd is $HOME/myproject/ and you issue the command
spyctl config current-context you will be shown the current
context in the global configuration. But if create initialize
a workspace and create a context, you will notice that your
current context is the one set within the workspace configuration
file.
For example:
# Create a workspace in the current working directory.
spyctl config init-workspace
# Create a context specific to a Linux Service.
spyctl config set-context –cgroup systemd:/system.slice/my_app.service –org my_organization –secret my_secret my_app_context
# Show the current context and see my_app_context in the output.
spyctl config current-context
Executing spyctl outside of a workspace directory or any of its subdirectories will revert the tool to using the current context in the global configuration file.
spyctl config init-workspace [OPTIONS]
Options
- -y, --yes, --assume-yes
Automatic yes to prompts; assume “yes” as answer to all prompts and run non-interactively.
Use “spyctl <command> –help” for more information about a given command.
set-apisecret
Set a new entry in the spyctl secrets file, or update an existing one.
spyctl config set-apisecret [OPTIONS] [NAME]
Options
- -k, --apikey, --api-key <api_key>
API key generated via the Spyderbat UI
- -u, --apiurl, --api-url <api_url>
URL target for api queries. Default: https://api.spyderbat.com
Arguments
- NAME
Optional argument
Use “spyctl <command> –help” for more information about a given command.
set-context
Set a context entry in a spyctl configuration file, or update an existing one.
spyctl config set-context [OPTIONS] NAME
Options
- -g, --global
When operating within a spyctl workspace, this sets a context in the global spyctl configuration file.
- -u, --use-context
Use this context when set. Sets the current-context field in the config file. The first context added to a config is automatically set as current-context.
- -s, --secret <secret>
Required Name of api config secret.
- -o, --organization, --org <organization>
Required ID or name of Spyderbat organization.
- -c, --cluster <cluster>
Name or Spyderbat ID of Kubernetes cluster.
- -n, --namespace <namespace>
Name or Spyderbat ID of Kubernetes namespace.
- -p, --pod <pod>
Name or Spyderbat ID of Kubernetes pod.
- -m, --machines <machines>
Name of machine group, or name or Spyderbat ID of a machine (node).
- -i, --image <image>
Name of container image, wildcards allowed.
- -d, --image-id <image_id>
Container image ID.
- -N, --container-name <container_name>
Name of specific container.
- -C, --cgroup <cgroup>
Linux service cgroup.
Arguments
- NAME
Required argument
Use “spyctl <command> –help” for more information about a given command.
use-context
Set the current-context in a spyctl configuration file.
spyctl config use-context [OPTIONS] NAME
Options
- -g, --global
When operating within a spyctl workspace, this changes the current context in the global configuration file.
Arguments
- NAME
Required argument
Use “spyctl <command> –help” for more information about a given command.
view
View the current spyctl configuration file. If operating within a workspace the default behavior displays a merged configuration including contexts from the global config and any other workspace configuration files from cwd to root.
spyctl config view [OPTIONS]
Options
- -g, --global
When operating within a spyctl workspace, this displays the global spyctl configuration file.
- -w, --workspace
When operating within a spyctl workspace, this displays only the workspace configuration file.
- -o, --output <output>
- Options:
yaml | json | default
Use “spyctl <command> –help” for more information about a given command.
create
Create a resource from a file.
spyctl create [OPTIONS] COMMAND [ARGS]...
Use “spyctl <command> –help” for more information about a given command.
notification-config
Create a Notification Config resource outputted to stdout.
spyctl create notification-config [OPTIONS]
Options
- -n, --name <name>
Required A name for the config.
- -T, --target <target>
Required The name or ID of a notification target. Tells the config where to send notifications.
- -P, --template <template>
The name or ID of a notification configuration template. If omitted, the config will be completely custom.
- -o, --output <output>
- Options:
yaml | json | default
Use “spyctl <command> –help” for more information about a given command.
notification-target
Create a Notification Target resource outputted to stdout.
spyctl create notification-target [OPTIONS]
Options
- -n, --name <name>
Required A name for the target. Used by other resources to refer to the configured target destination.
- -T, --type <tgt_type>
Required The type of destination for the target.
- Options:
emails | slack | sns | webhook
- -o, --output <output>
- Options:
yaml | json | default
Use “spyctl <command> –help” for more information about a given command.
policy
Create a Guardian Policy object from a file, outputted to stdout
spyctl create policy [OPTIONS]
Options
- -f, --from-file <filename>
Required File that contains the FingerprintsGroup or SpyderbatBaseline object, from which spyctl creates a Guardian Policy
- -o, --output <output>
- Options:
yaml | json | default
- -n, --name <name>
Optional name for the Guardian Policy, if not provided, a name will be generated automatically
- -d, --disable-processes <disable_procs>
Disable processes detections for this policy. Disabling all processes detections effectively turns this into a network policy.
- Options:
all
- -D, --disable-connections <disable_conns>
Disable detections for all, public, or private connections.
- Options:
all | egress | ingress | private | private-egress | private-ingress | public | public-egress | public-ingress
- --include-imageid
Include the image id in the container selector when creating the policy.
- -m, --mode <mode>
This determines what the policy should do when applied and enabled. Default is audit mode. Audit mode will generate log messages when a violation occurs and when it would have taken an action, but it will not actually take an action or generate a violation flag. Enforce mode will take actions, generate flags, and also generate audit events.
- Options:
enforce | audit
- --colorize, --no-colorize
Specify coloration on or off. Default is on.
Use “spyctl <command> –help” for more information about a given command.
suppression-policy
Create a Suppression Policy object from a file, outputted to stdout
spyctl create suppression-policy [OPTIONS] TYPE
Options
- -i, --id <trace_id>
UID of the object to build a Suppression Policy from.
- -o, --output <output>
- Options:
yaml | json | default
- -u, --auto-generate-user-scope
Auto generate the users in the suppression policies userSelector if’–id’ is provided.
- -n, --name <name>
Optional name for the Suppression Policy, if not provided, a name will be generated automatically
- -m, --mode <mode>
This determines what the policy should do when applied and enabled. Default is audit mode. Audit mode will generate log messages when a an object matches the policy and would be suppressed, but it will not suppress the object. Enforce mode actually suppress the object if it matches the policy.
- Options:
enforce | audit
- --users <users>
Scope the policy to these users. This option will overwrite any auto-generated users values generated using ‘–id’
- --colorize, --no-colorize
Specify coloration on or off. Default is on.
Arguments
- TYPE
Required argument
Use “spyctl <command> –help” for more information about a given command.
delete
Delete resources by resource and name, or by resource and ids
spyctl delete [OPTIONS] RESOURCE [NAME_OR_ID]
Options
- -y, --yes, --assume-yes
Automatic yes to prompts; assume “yes” as answer to all prompts and run non-interactively.
Arguments
- RESOURCE
Required argument
- NAME_OR_ID
Optional argument
Use “spyctl <command> –help” for more information about a given command.
describe
Describe a Spyderbat resource
spyctl describe [OPTIONS] RESOURCE [NAME_OR_ID]
Options
- -f, --filename <filename>
File to diff with target.
Arguments
- RESOURCE
Required argument
- NAME_OR_ID
Optional argument
Use “spyctl <command> –help” for more information about a given command.
diff
Diff target Baselines and Policies with other Resources.
Diff’ing in Spyctl requires a target Resource (e.g. a Baseline or Policy
document you are maintaining) and a Resource to diff with the target. A target can be either a local file supplied using the -f option or a policy you’ve applied to the Spyderbat Backend supplied with the -p option. By default, target’s are diff’d with deviations if they are applied policies, otherwise they are diff’d with relevant* Fingerprints from the last 24 hours to now. Targets may also be diff’d with local files with the -w option or with data from an existing applied policy using the -P option.
The output of a diff shows you any lines that would be added to or removed
from your target Resource as a result of a Merge. diffs may also be performed in bulk. Bulk diffs are outputted to a pager like ‘less’ or ‘more’.
To maintain a target Resource effectively, the goal should be to get to
get to a point where the diff no longer displays added or removed lines (other than timestamps).
Each policy has one or more Selectors in its spec field,
relevant Fingerprints are those that match those Selectors.
For time field options such as –start-time and –end-time you can use (m) for minutes, (h) for hours (d) for days, and (w) for weeks back from now or provide timestamps in epoch format.
Note: Long time ranges or “get” commands in a context consisting of multiple machines can take a long time.
spyctl diff [OPTIONS]
Options
- -f, --filename <filename>
Target file(s) of the diff. This argument is mutually exclusive with arguments: [policy].
- -p, --policy <policy>
Target policy name(s) or uid(s) of the diff. If supplied with no argument, set to ‘all’. This argument is mutually exclusive with arguments: [filename].
- -w, --with-file <with_file>
File to diff with target. This argument is mutually exclusive with arguments: [with_policy].
- -P, --with-policy <with_policy>
Policy uid to diff with target. If supplied with no argument then spyctl will attempt to find a policy matching the uid in the target’s metadata. This argument is mutually exclusive with arguments: [with_file].
- -l, --latest
Diff target with latest records using the value of ‘latestTimestamp’ in ‘metadata’. This replaces –start-time.
- -t, --start-time <st>
Start time of the query for fingerprints to diff. Only used if –latest, –with-file, –with-policy are not set. Default is 24 hours ago.
- -e, --end-time <et>
End time of the query for fingerprints to diff. Only used if –with-file, and –with-policy are not set. Default is now.
- --full-diff
A diff summary is shown by default, set this flag to show the full object when viewing a diff. (All changes to the object are shown in the summary).
- -o, --output <output>
- Options:
yaml | json | default
- -y, --yes, --assume-yes
Automatic yes to prompts; assume “yes” as answer to all prompts and run non-interactively.
- --include-network, --exclude-network
Include or exclude network data in the diff. Default is to include network data in the diff.
- --colorize, --no-colorize
Specify coloration on or off. Default is on.
Use “spyctl <command> –help” for more information about a given command.
edit
Edit resources by resource and name, or by resource and ids
spyctl edit [OPTIONS] [RESOURCE] [NAME_OR_ID]
Options
- -f, --filename <filename>
Filename to use to edit the resource.
- -y, --yes, --assume-yes
Automatic yes to prompts; assume “yes” as answer to all prompts and run non-interactively.
Arguments
- RESOURCE
Optional argument
- NAME_OR_ID
Optional argument
Use “spyctl <command> –help” for more information about a given command.
export
Export Spyderbat Resources for later use to import.
spyctl export [OPTIONS] RESOURCE [NAME_OR_ID]
Options
- -E, --exact, --exact-match
Exact match for NAME_OR_ID. This command’s default behaviordisplays any resource that contains the NAME_OR_ID.
Arguments
- RESOURCE
Required argument
- NAME_OR_ID
Optional argument
Use “spyctl <command> –help” for more information about a given command.
get
Display one or many Spyderbat Resources.
See https://spyctl.readthedocs.io/en/latest/user/resources.html for a full list of available resource.
For time field options such as –start-time and –end-time you can use (m) for minutes, (h) for hours (d) for days, and (w) for weeks back from now or provide timestamps in epoch format.
Note: Long time ranges or “get” commands in a context consisting of multiple machines can take a long time.
spyctl get [OPTIONS] RESOURCE [NAME_OR_ID]
Options
- --image <image>
Only show resources tied to this container image. Overrides value current context if it exists.
- --image-id <imageID>
Only show resources tied to containers running with this image id. Overrides value current context if it exists.
- --container-name <containerName>
Only show resources tied to containers running with this container name. Overrides value current context if it exists.
- --container-id <containerID>
Only show resources tied to containers running with this container id. Overrides value current context if it exists.
- --cgroup <cgroup>
Only show resources tied to machines running Linux services with this cgroup. Overrides value current context if it exists.
- --pod <pod>
Only show resources tied to this pod uid. Overrides value current context if it exists.
- --machines, --nodes <machines>
Only show resources to these nodes. Overrides value current context if it exists.
- --namespace <namespace>
Only show resources tied to this namespace. Overrides value current context if it exists.
- --cluster <cluster>
Only show resources tied to this cluster. Overrides value current context if it exists.
- -o, --output <output>
- Options:
yaml | json | default | wide
- -E, --exact, --exact-match
Exact match for NAME_OR_ID. This command’s default behaviordisplays any resource that contains the NAME_OR_ID.
- -t, --start-time <st>
Start time of the query. Default is 24 hours ago.
- -e, --end-time <et>
End time of the query. Default is now.
- --ndjson
If output is ‘json’ this outputs each json record on its own line
Arguments
- RESOURCE
Required argument
- NAME_OR_ID
Optional argument
Use “spyctl <command> –help” for more information about a given command.
import
Import previously exported policies by file name into a new organization context.
spyctl import [OPTIONS]
Options
- -f, --filename <filename>
Required Filename containing policies to import.
Use “spyctl <command> –help” for more information about a given command.
logs
Print the logs for a specified resource. Default behavior is to print out the logs for the last 24 hours.
spyctl logs [OPTIONS] RESOURCE [NAME_OR_ID]
Options
- -f, --follow
Specify if the logs should be streamed
- -t, --start-time <st>
Get logs since this time. Default is 24 hours ago.
- -e, --end-time <et>
End time of the query. Default is now.
- --tail <tail>
Lines of recent log file to display. Defaults to -1.
- --timestamps
Include timestamps on each line in the log output.
- --full
Show the full log, not just the description.
- --since-iterator <since_iterator>
Retrieve all logs since the provided iterator.
Arguments
- RESOURCE
Required argument
- NAME_OR_ID
Optional argument
Use “spyctl <command> –help” for more information about a given command.
merge
Merge target Baselines and Policies with other Resources.
Merging in Spyctl requires a target Resource (e.g. a Baseline or Policy
document you are maintaining) and a Resource to merge into the target. A target can either be a local file supplied using the -f option or a policy you’ve applied to the Spyderbat Backend supplied with the -p option. By default, target’s are merged with deviations if they are applied policies, otherwise they are merged with relevant* Fingerprints from the last 24 hours to now. Targets may also be merged with local files with the -w option or with data from an existing applied policy using the -P option.
When merging a single local file with another resource, the output will
be sent to stdout. WARNING: Do not redirect output to the same file you used as input. You may use the -O flag to output the merged data to a unique file with a name generate by Spyctl.
When bulk merging local files, the output for each merge operation will
be outputted to unique files generated by Spyctl (the same as supplying the -O flag mentioned above).
When merging existing applied policies in bulk or individually, the default
destination for the output will be to apply it directly to the Spyderbat Backend (you will have a chance to review the merge before any changes are applied). This removes the requirement to deal with local files when managing policies. However, it is a good idea to back up policies in a source-control repository. You can also use the -O operation to send the output of this merge to a local file.
Each policy has one or more Selectors in its spec field,
relevant Fingerprints are those that match those Selectors.
For time field options such as –start-time and –end-time you can use (m) for minutes, (h) for hours (d) for days, and (w) for weeks back from now or provide timestamps in epoch format.
Note: Long time ranges or “get” commands in a context consisting of multiple machines can take a long time.
spyctl merge [OPTIONS]
Options
- -f, --filename <filename>
Target file(s) of the merge. This argument is mutually exclusive with arguments: [policy].
- -p, --policy <policy>
Target policy name(s) or uid(s) of the merge. If supplied with no argument, set to ‘all’. This argument is mutually exclusive with arguments: [filename].
- -w, --with-file <with_file>
File to merge into target. This argument is mutually exclusive with arguments: [with_policy].
- -P, --with-policy <with_policy>
Policy uid to merge with target. If supplied with no argument then spyctl will attempt to find a policy matching the uid in the target’s metadata. This argument is mutually exclusive with arguments: [with_file].
- -l, --latest
Merge file with latest records using the value of ‘latestTimestamp’ in the target’s ‘metadata’. This replaces –start-time.
- -o, --output <output>
- Options:
yaml | json | default
- -t, --start-time <st>
Start time of the query for fingerprints to merge. Only used if –latest, –with-file, and –with-policy are not set. Default is 24 hours ago.
- -e, --end-time <et>
End time of the query for fingerprints to merge. Only used if –with-file and –with-policy are not set. Default is now.
- -O, --output-to-file
Should output merge to a file. Unique filename created from the name in the object’s metadata.
- --full-diff
A diff summary is shown by default, set this flag to show the full object when viewing a diff following a merge. (All changes to the object are shown in the summary).
- -y, --yes, --assume-yes
Automatic yes to prompts; assume “yes” as answer to all prompts and run non-interactively. This argument is mutually exclusive with arguments: [yes_except].
- -Y, --yes-except, --assume-yes-except-review
Automatic yes to merge prompts; assume “yes” as answer to all merge prompts but still prompts review of policy updates before applying. This argument is mutually exclusive with arguments: [yes].
- --include-network, --exclude-network
Include or exclude network data in the merge. Default is to include network data in the merge.
- --colorize, --no-colorize
Specify coloration on or off. Default is on.
Use “spyctl <command> –help” for more information about a given command.
show-schema
Display the schema of a specific resource
spyctl show-schema [OPTIONS] {baseline|config|fingerprint|fingerprint-
group|policy|cluster-policy|secret|suppression-policy|uid-
list}
Arguments
- KIND
Required argument
Use “spyctl <command> –help” for more information about a given command.
suppress
Tune your environment by suppressing Spyderbat Resources
spyctl suppress [OPTIONS] COMMAND [ARGS]...
Use “spyctl <command> –help” for more information about a given command.
trace
Suppress one or many Spyderbat Resources
spyctl suppress trace [OPTIONS]
Options
- -i, --id <resrc_id>
Required id of the spydertrace or spydertrace summary to suppress
- -u, --include-users
Scope the trace suppression policy to the users found in the trace
- -y, --yes, --assume-yes
Automatic yes to prompts; assume “yes” as answer to all prompts and run non-interactively.
Use “spyctl <command> –help” for more information about a given command.
test-notification
Send test notifications to Targets or Notification Routes.
Targets are named destinations like email, slack hooks, webhooks, or sns topics. Notification Routes define which notifications are send to which targets. Testing a notification route will send a test notification to one or many targets it is configured with.
spyctl test-notification [OPTIONS]
Options
- -T, --targets <targets>
Comma-delimitated list of target names to send a test notification to. Use ‘spyctl get notification-targets’ to see what is available.
Use “spyctl <command> –help” for more information about a given command.
validate
Validate spyderbat resource and spyctl configuration files.
spyctl validate [OPTIONS]
Options
- -f, --filename <file>
Required Target file to validate
- --colorize, --no-colorize
Specify coloration on or off. Default is on.
Use “spyctl <command> –help” for more information about a given command.
revision 4