csw-tools

A collection of automation utilities for Cisco Secure Workload (CSW, formerly Tetration), available through a single command-line package.

Current utilities

These core utilities set up csw-tools for general use:

Command	Description	Documentation
init	Create or replace the per-user config.toml	Guide
configure-credentials	Inspect or replace CSW API credentials in the OS keyring	Guide

The following command is implemented for production use:

Command	Description	Documentation
create-scopes	Create scopes in bulk from CSV	Guide

The following commands are in DEV/TESTING state and generally should not be used in production yet:

Command	Description	Documentation
clean-stale-labels	Remove old static labels for workloads absent from current inventory	Guide
convert-labels	Persist observed inventory fields as per-workload static labels	Guide
prune-agents	Preview and destructively decommission stale agents and clean explicit related objects	Guide
prune-policy	Not implemented: remove or filter entries within a workspace policy	Guide
sync-collection-rules	Not implemented: validate collection rules against scope and filter IPs	Guide

Installation

The project requires Python 3.12 or later. uv is the preferred installation and development tool, although normal Python package installation also works.

Once uv is installed, install the package as a tool:

uv tool install csw-tools

Usage

List the available commands, common options, and project version information:

csw-tools --help
csw-tools --version

Global options must appear before the command name. The command and its own options follow:

csw-tools create-scopes scopes.csv
csw-tools --dashboard my-company.tetrationcloud.com prune-agents
csw-tools -d my-company configure-credentials

Command-generated files use csw-tools-outputs/ in the current working directory and a basic CLI log is enabled by default.

Every command's guide is linked from the tables above. The command help is the authoritative option list:

csw-tools COMMAND --help

CSW Dashboard Selection

A dashboard may be supplied as its short SaaS name, a full FQDN, or an HTTPS origin:

csw-tools -d my-company COMMAND
csw-tools -d my-company.tetrationcloud.com COMMAND
csw-tools -d mycsw.example.org COMMAND
csw-tools -d https://mycsw.example.org COMMAND

A short name is auto-appended by default with .tetrationcloud.com. Any FQDN is used as given with HTTPS. IP addresses and single-label on-premises hosts require HTTPS:// explicitly, such as -d https://192.0.2.10 or -d https://csw-local.

TLS certificate verification is enabled by default. Use --no-dashboard-verify-tls only for a trusted deployment whose certificate cannot be validated normally.

Configuration

Settings are resolved in this order:

1. CLI arguments
2. config.toml values
3. Backend defaults from config_defaults.py
4. Interactive prompt for an unresolved required value

config.toml is optional but useful for values that are reused often. Create or replace it interactively with:

csw-tools init

This copies the packaged config.example.toml to the OS-native per-user location:

• macOS: ~/Library/Application Support/csw-tools/config.toml
• Linux: ${XDG_CONFIG_HOME:-~/.config}/csw-tools/config.toml
• Windows: %APPDATA%\csw-tools\config.toml

If needed, use --config PATH before the command name to select a different file.

Common output behavior can be reused across every command:

[common]
output_dir = "csw-tools-outputs"
log_cli_output = true

Relative output paths are resolved from the current working directory. Absolute paths and paths beginning with ~ are also accepted. CLI transcript logging is enabled by default; disable it for one run with --no-log-cli-output before the command name. Each transcript combines stdout and stderr in a plain-text file named csw-tools-COMMAND-YYYYMMDDTHHMMSSmmmZ.log, prints its absolute path to stderr in quotes when logging starts, and never records entered prompt values. Root help, version output, unknown commands, and errors raised before configuration can be resolved do not create transcripts.

Credentials

Secrets are stored through the operating system keyring and are never written to config.toml or a backup. For a dashboard named my-company, the default identifiers are:

Service name	Username	Stored value
csw-tools:my-company	csw:api_key	CSW API key
csw-tools:my-company	csw:api_secret	CSW API secret

Inspect or replace the credential pair interactively:

csw-tools -d my-company configure-credentials

(If using a CSW Dashboard that is not .tetrationcloud.com, then the full HTTPS url is used instead as part of the service name)

Safe Change Workflow

Mutating commands default to --dry-run; review the complete plan before using --apply. Supported commands create a timestamped JSON backup before the first API mutation in the common output directory and update it around each attempted operation. Keep backups until the results have been validated.

Rollback support and limitations differ by command. Read the individual command guide before applying or recovering changes. Agent decommissioning has no true rollback.

Development

See DEV-GUIDELINES.md for architecture, shared APIs, contributor workflow, and project checks.