qualys-cli 0.1.1__tar.gz

qualys_cli-0.1.1/.gitignore

@@ -0,0 +1,40 @@
+.venv/
+.install-check/
+__pycache__/
+*.pyc
+*.pyo
+.cache/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# Development / internal files (not for PyPI)
+CLAUDE.md
+.claude/
+user-prefs-export.xml
+api-model.json
+docs/design.md
+packaging/

qualys_cli-0.1.1/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to `qualys-cli` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] — 2026-07-08
+
+### Security
+- `locked_mode` is now actually enforced (previously documented but a no-op):
+  refuses free-form `--output-file` writes, suppresses `-v`/`-vv` request
+  logging, and refuses to run against a profile that still has a plaintext
+  password in `config.toml`.
+- Fixed a path-traversal vulnerability in command history (`--profile` /
+  `qualys-cli replay <correlation_id>`) that could read or write files outside
+  the history directory.
+- Removed the wildcard `Access-Control-Allow-Origin: *` CORS header from the
+  local `qualys-cli serve` HTTP server — it allowed any website open in the
+  operator's browser to drive `POST /run` (arbitrary command execution)
+  cross-origin.
+- `qualys-cli configure`: a failed/unavailable OS keyring write no longer
+  silently loses the password. It now falls back to plaintext storage in
+  `config.toml` with an explicit warning (previously the credential was
+  stored nowhere and auth failed on the next command with a confusing error).
+- `--password` on `qualys-cli configure` now warns that passing secrets as a
+  CLI flag can leak via shell history / `ps`; prefer the interactive prompt
+  or `QUALYS_PASSWORD`.
+- Tightened the POST-retry heuristic so mutating endpoints that happen to
+  contain `/search/` or `/count/` in their path (e.g. `.../search/reset`,
+  `.../count/purge`) are no longer auto-retried as if they were idempotent.
+
+### Fixed
+- `pc scan-schedule list` / `delete`: corrected endpoint from
+  `/api/2.0/fo/schedule/compliance/` to `/api/2.0/fo/schedule/scan/compliance/`.
+- `pc option-profile list`: corrected endpoint from
+  `/api/2.0/fo/subscription/option_profile/compliance/` to
+  `.../option_profile/pc/`.
+- `tc evaluation list`: now requires `--account-id` and targets
+  `/cloudview-api/rest/v1/{provider}/evaluations/{accountId}` per the API spec
+  (the previous unparameterised path returned 404).
+- `pm job get` / `runs` / `summary` / `create` / `update`: corrected to use the
+  documented `/pm/v1/deploymentjob/...` (singular) family. `update` switched
+  from PUT to PATCH at `/pm/v1/deploymentjob/update/{id}`. `summary` now hits
+  `.../{id}/deploymentjobresult/summary`.
+- `pm job change-status`: rewritten to match
+  `POST /pm/v1/deploymentjobs/update/status/{Enabled|Disabled}` with `jobIds`
+  body — accepts a comma-separated list of job IDs and an action argument.
+- `csam domain count`: switched from GET to POST and added optional
+  `--type` / `--filter-type` per the documented body parameters.
+- `csam org count`: added missing `--format` / `--output-file` flags so
+  `--format json` no longer rejects the option.
+- `was scan status`: added missing `--format` / `--output-file` flags.
+- `batch --output-file` to a path with a missing parent directory now creates
+  the directory (or fails cleanly) instead of crashing with an unhandled
+  `OSError`.
+
+### Changed
+- `vm kb list` now requires at least one scoping flag
+  (`--ids`, `--id-min`/`--id-max`, `--cve`, `--published-after`, or
+  `--last-modified-after`). The unfiltered KnowledgeBase exceeded the request
+  read timeout and the in-memory body cap.
+- `pc posture list`: `--policy-id` is now required (the API mandates it; the
+  previous behaviour surfaced a backend error).
+
+## [0.1.0] — 2026-05-02
+
+Initial public release.
+
+### Added
+- Coverage of 273 Qualys REST endpoints across modules: VM, PC, PM, ETM, WAS,
+  TotalCloud (TC), Cloud Agent (CA), Container Security (CS), CSAM, Asset, User,
+  Subscription (Sub), Scan Auth.
+- Dual auth: HTTP Basic and JWT Bearer, selected per-command. JWT tokens are
+  fetched via `/auth` and cached in the local config file; refreshed on 401.
+- API gateway routing: PM, ETM, CS, CSAM, TC, and CA config commands target
+  the regional gateway URL automatically.
+- Profile system with credentials resolved from env vars → OS keyring →
+  `~/.config/qualys-cli/config.toml`. Multiple named profiles supported via
+  `--profile` or `QUALYS_PROFILE`.
+- Platform auto-detection from username — sets API and gateway URLs based on
+  the user's Qualys POD without manual configuration.
+- Output modes: `interactive` (rich tables + colours) and `agentic` (JSON, no
+  decoration) — switchable via `qualys-cli mode <mode>` or
+  `QUALYS_OUTPUT_MODE`. Per-command overrides via `--format json|jsonl|yaml|table`.
+- Bulk export to file via `--output-file` (JSON / YAML auto-detected from
+  extension); table still rendered to terminal.
+- Pagination helpers for both Qualys QPS XML cursor responses and JSON
+  page-numbered APIs.
+- Automatic retry with exponential backoff on connection errors and 5xx; honours
+  `Retry-After` on 429.
+- Structured error extraction from XML (`SIMPLE_RETURN`, `ServiceResponse`) and
+  JSON error bodies. Errors emitted as JSON on stderr when stderr is not a TTY.
+- `-v` / `-vv` request logging (secrets never logged).
+- `qualys-cli configure` interactive wizard and `qualys-cli profiles` listing.
+
+### Internal
+- 30 unit tests covering client, formatters, agent mode, and PM smoke tests.
+- Strict mypy on core modules (`client`, `config`, `formatters`, `auth`,
+  `platforms`); relaxed on auto-generated command modules.
+- Ruff lint clean (E, F, I, UP, B, C4, SIM rule sets).
+- Codegen pipeline (`scripts/`) is opt-in via the `codegen` extra.
+
+[Unreleased]: https://github.com/qualys/qualys-cli/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/qualys/qualys-cli/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/qualys/qualys-cli/releases/tag/v0.1.0

qualys_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qualys-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qualys_cli-0.1.1/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: qualys-cli
+Version: 0.1.1
+Summary: Command-line interface for the Qualys REST APIs (VM, PC, PM, ETM, WAS, TC, CA, CS, CSAM, Sub, Asset, User).
+Project-URL: Homepage, https://github.com/qualys/qualys-cli
+Project-URL: Documentation, https://github.com/qualys/qualys-cli#readme
+Project-URL: Issues, https://github.com/qualys/qualys-cli/issues
+Project-URL: Changelog, https://github.com/qualys/qualys-cli/blob/main/CHANGELOG.md
+Author: qualys-cli contributors
+License: MIT License
+        
+        Copyright (c) 2026 qualys-cli contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,cspm,patch-management,qualys,security,vm,vulnerability-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: brotli>=1.1
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=24
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer<0.26,>=0.12
+Requires-Dist: xmltodict>=0.13
+Requires-Dist: zstandard>=0.22
+Provides-Extra: codegen
+Requires-Dist: anthropic>=0.30; extra == 'codegen'
+Requires-Dist: defusedxml>=0.7; extra == 'codegen'
+Requires-Dist: pydantic>=2; extra == 'codegen'
+Requires-Dist: pypdf>=4; extra == 'codegen'
+Requires-Dist: selectolax>=0.3; extra == 'codegen'
+Requires-Dist: trafilatura>=1.9; extra == 'codegen'
+Description-Content-Type: text/markdown
+
+# qualys-cli
+
+[![CI](https://github.com/qualys/qualys-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/qualys/qualys-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/qualys-cli.svg)](https://pypi.org/project/qualys-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/qualys-cli.svg)](https://pypi.org/project/qualys-cli/)
+[![License](https://img.shields.io/pypi/l/qualys-cli.svg)](LICENSE)
+
+A unified command-line interface for the Qualys REST APIs — covering VM, PC,
+Patch Management, ETM, WAS, TotalCloud (TC), Cloud Agent (CA), Container
+Security (CS), CSAM, Subscription, Asset, and User management. Rich table
+output, JSON / YAML / JSONL export, automatic retry with backoff, JWT auto-
+refresh, OS-keyring credential storage, and a clean machine-readable mode for
+scripting and AI agents.
+
+```text
+  ╭─────────────────────────────────────────────────╮
+  │  qualys-cli   ·   273 endpoints, one CLI        │
+  │  vm · pc · pm · etm · was · tc · ca · cs        │
+  │  csam · sub · asset · user · scanauth           │
+  ╰─────────────────────────────────────────────────╯
+```
+
+## Install
+
+```bash
+# End user (recommended)
+pipx install qualys-cli
+
+# Or from source
+pipx install git+https://github.com/qualys/qualys-cli
+
+# Development
+git clone https://github.com/qualys/qualys-cli && cd qualys-cli
+uv sync
+uv run qualys-cli --help
+```
+
+Python 3.11+ required. Works on macOS, Linux, and Windows.
+
+## Quick start
+
+```bash
+# 1. Configure credentials (interactive — password stored in OS keyring)
+qualys-cli configure
+
+# 2. Run any command
+qualys-cli vm host list --limit 10
+qualys-cli was webapp list
+qualys-cli pm job list --format json
+```
+
+### Non-interactive setup (CI / Docker)
+
+```bash
+qualys-cli configure \
+  --url https://qualysapi.qualys.com \
+  --username "$QUALYS_USERNAME" \
+  --password "$QUALYS_PASSWORD" \
+  --output-mode agentic
+```
+
+Credentials resolve in this priority order:
+1. `QUALYS_URL` / `QUALYS_USERNAME` / `QUALYS_PASSWORD` / `QUALYS_TOKEN` env vars
+2. OS keyring (per-profile entry)
+3. `~/.config/qualys-cli/config.toml`
+
+Multiple profiles via `--profile <name>` or `QUALYS_PROFILE`. List with `qualys-cli profiles`.
+
+## Output modes
+
+The CLI has two top-level modes that govern the *default* output style:
+
+| Mode          | Default output                  | Spinners / colours | Use case                     |
+|---------------|---------------------------------|--------------------|------------------------------|
+| `interactive` | Rich table (first 25 rows)      | Yes                | Humans in a terminal         |
+| `agentic`     | JSON, no decoration             | No                 | Scripts, pipelines, AI agents |
+
+Switch the persistent default for a profile:
+
+```bash
+qualys-cli mode                # show current
+qualys-cli mode agentic        # set agentic
+qualys-cli mode interactive    # set interactive
+```
+
+Or set per-shell with `export QUALYS_OUTPUT_MODE=agentic`.
+
+### Per-command output flags
+
+These work on every command and override the mode default:
+
+| Flag                          | Behaviour                                                      |
+|-------------------------------|----------------------------------------------------------------|
+| `--format json`               | Full JSON to stdout                                            |
+| `--format jsonl`              | One flattened JSON object per line (JSON Lines / NDJSON)       |
+| `--format yaml`               | YAML to stdout                                                 |
+| `--format table`              | Rich table (forced)                                            |
+| `--limit 0`                   | Remove the default 25-row cap                                  |
+| `--output-file results.json`  | Dump full data to file (extension picks JSON or YAML)          |
+| `-v`, `-vv`                   | Log requests (and response sizes); secrets never logged        |
+
+## Examples by module
+
+### VM (Vulnerability Management)
+```bash
+qualys-cli vm host list --ips 10.0.0.0/24
+qualys-cli vm host detection --ips 10.0.0.0/24
+qualys-cli vm scan launch --title "Weekly" --ip 10.0.1.0/24 --option-id 12345
+qualys-cli vm scan fetch SCAN-REF-123 --output-file results.json
+```
+
+### Patch Management (PM)
+```bash
+qualys-cli pm job list --format json
+qualys-cli pm job create --name "Critical patches" \
+  --patch-ids "12345,67890" --asset-group-ids "AG-1"
+qualys-cli pm patch list --severity Critical
+```
+
+### Web Application Scanning (WAS)
+```bash
+qualys-cli was webapp list --name "prod"
+qualys-cli was webapp get 12345
+qualys-cli was scan launch --webapp-id 12345 --name "Nightly WAS"
+qualys-cli was finding list --webapp-id 12345 --severity 5
+qualys-cli was report download 99999 --output-file was-report.pdf
+```
+
+### TotalCloud (TC) — CSPM
+```bash
+qualys-cli tc connector list --provider AWS
+qualys-cli tc evaluation list --provider AWS --account-id 123456789012
+qualys-cli tc rule list --cloud-type AWS --rule-type simple_alert
+qualys-cli tc exception list
+```
+
+### Cloud Agent (CA), Container Security (CS), CSAM
+```bash
+qualys-cli ca agent list --status Active
+qualys-cli ca actkey create --title "Linux Prod" --modules VM,PC
+
+qualys-cli cs image list --filter "vulns.severity5Count:>0"
+qualys-cli cs image get <sha>
+qualys-cli cs container list --severity Critical
+
+qualys-cli csam asset list --updated-after 2026-01-01T00:00Z
+qualys-cli csam vuln list-easm --filter "vulnerability.cvss=GREATER=7"
+```
+
+### Subscription, Asset, User
+```bash
+qualys-cli sub info
+qualys-cli sub export --output-file sub-backup.xml
+qualys-cli asset ip add --ips 10.0.0.0/24 --tracking-method IP
+qualys-cli user create --username jdoe --first-name Jane --last-name Doe \
+  --email jane@example.com --user-role scanner
+```
+
+Tip: append `--help` to any command (e.g. `qualys-cli was scan launch --help`)
+for the full flag set.
+
+## Documentation
+
+A comprehensive usage reference with all 273 endpoints is included in the package:
+- **Source install**: `docs/usage.html` in the repository
+- **Pip install**: Located in your Python environment's `share/qualys-cli/docs/usage.html`
+
+To find it after installation:
+```bash
+python -c "import sys; print(sys.prefix + '/share/qualys-cli/docs/usage.html')"
+```
+
+## LLM / agent usage
+
+The CLI is built to be safe to drive from a script or an AI agent:
+
+```bash
+# JSON output (set agentic mode persistently, or use --format json per call)
+qualys-cli mode agentic
+qualys-cli vm host list | jq '.HOST_LIST_OUTPUT.RESPONSE.HOST_LIST'
+
+# JSON Lines — one record per line, ideal for streaming
+qualys-cli pm job list --format jsonl | jq -r '.id'
+
+# Errors emitted as JSON on stderr when stderr is not a TTY
+qualys-cli --profile nonexistent vm host list 2>/tmp/err.json
+# {"error": "No username for profile 'nonexistent'...", "type": "configuration_error"}
+```
+
+**Behaviour contract for agents:**
+- `stdout` contains only data (JSON / JSONL / YAML / table text).
+- `stderr` carries status, spinners, and human-readable errors. All decoration
+  is suppressed when stderr is not a TTY.
+- Exit code `0` = success, `1` = any error.
+- When stderr is not a TTY, errors are emitted as
+  `{"error": "...", "type": "..."}` JSON.
+
+## Authentication
+
+| Module group                                 | Auth        | Endpoint family                  |
+|----------------------------------------------|-------------|----------------------------------|
+| VM, PC, Asset, User, ScanAuth, Sub, WAS      | HTTP Basic  | `/api/2.0/fo/`, `/qps/rest/`     |
+| TC, PM, ETM, CS, CSAM                        | JWT Bearer  | API gateway (`/csapi/`, `/etm/`) |
+| CA agent ops                                 | HTTP Basic  | `/qps/rest/`                     |
+| CA activation-key / config                   | JWT Bearer  | `/caui/v1/`                      |
+
+JWT tokens are fetched via `POST /auth`, cached in `config.toml`, and
+auto-refreshed on 401.
+
+## Development
+
+```bash
+uv sync
+uv run pytest                # tests
+uv run ruff check src/       # lint
+uv run mypy src/             # type check
+uv run qualys-cli --help     # smoke
+uv build                     # build sdist + wheel into dist/
+```
+
+### Regenerating commands from Qualys docs
+
+The codegen pipeline is opt-in via the `codegen` extra (it pulls in
+`anthropic`, `trafilatura`, `selectolax`, `pypdf`):
+
+```bash
+uv sync --extra codegen
+export ANTHROPIC_API_KEY=sk-ant-...
+uv run scripts/ingest_docs.py        # cache HTML pages
+uv run scripts/extract_endpoints.py  # LLM extraction → api-model.json
+uv run scripts/generate_commands.py  # regenerate commands/*.py
+```
+
+Generated files are marked with `# Auto-generated from api-model.json` and are
+safe to overwrite. Files without that header are treated as hand-edited and
+left alone.
+
+## Releasing
+
+Releases are published to PyPI by GitHub Actions on a tag push:
+
+```bash
+# Bump version in pyproject.toml, update CHANGELOG.md, commit
+git tag v0.1.1 && git push --tags
+```
+
+PyPI publishing uses Trusted Publishing (OIDC) — no API token is stored.
+Configure once at https://pypi.org/manage/project/qualys-cli/settings/publishing/.
+
+## License
+
+[MIT](LICENSE)