Metadata-Version: 2.4
Name: csw-tools
Version: 0.3.1
Summary: A collection of automation utilities for Cisco Secure Workload (CSW), available through this single package.
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Dist: click>=8.4.2
Requires-Dist: keyring>=25.7.0
Requires-Dist: rich>=15.0.0
Requires-Dist: tetpyclient>=1.0.8
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/structured-com/csw-tools
Project-URL: Issues, https://github.com/structured-com/csw-tools/issues
Description-Content-Type: text/markdown

# csw-tools

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


## Available Commands

| Command | Status | What it does | Docs |
|---|---|---|---|
| `init` | Core | Create or replace the user's `config.toml`. | [Guide](src/csw_tools/commands/init/README.md) |
| `configure-credentials` | Core | Set user CSW API credentials in the OS keyring | [Guide](src/csw_tools/commands/configure_credentials/README.md) |
| `create-scopes` | Production | Create scopes in bulk from .CSV | [Guide](src/csw_tools/commands/create_scopes/README.md) |
| `clean-stale-labels` | DEV/TESTING | Remove static labels for workloads absent from inventory | [Guide](src/csw_tools/commands/clean_stale_labels/README.md) |
| `convert-labels` | DEV/TESTING | Persist dynamic labels as static labels | [Guide](src/csw_tools/commands/convert_labels/README.md) |
| `prune-agents` | DEV/TESTING | Preview and decommission stale agents and related objects | [Guide](src/csw_tools/commands/prune_agents/README.md) |
| `prune-policy` | DEV/TESTING | Remove or filter entries within a workspace policy | [Guide](src/csw_tools/commands/prune_policy/README.md) |
| `sync-collection-rules` | DEV/TESTING | Validate collection rules against scope and filter IPs | [Guide](src/csw_tools/commands/sync_collection_rules/README.md) |

## Installation

The project requires Python 3.12 or later. [uv](https://docs.astral.sh/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:

```console
uv tool install csw-tools
```

## Usage

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

```console
csw-tools --help
csw-tools --version
```

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

```console
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:

```console
csw-tools COMMAND --help
```

## CSW Dashboard Selection

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

```console
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:

```console
csw-tools init
```

This copies the packaged
[`config.example.toml`](src/csw_tools/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.



## Credentials

Secrets are stored through the operating system keyring. 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/replace the credential pair with:

```console
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

Most edit/write commands default to `--dry-run`; review the complete plan before using
`--apply`. Supported commands create a timestamped JSON backup before the first
API change in the common output directory and update it around each attempted
operation. 

Rollback support and limitations differ by command. Read the individual command
guide before applying or recovering changes. 

## Development

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