qualys-cli 0.1.1__py3-none-any.whl

qualys_cli-0.1.1.dist-info/METADATA

@@ -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)

qualys_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,37 @@
+qualys_cli/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+qualys_cli/__main__.py,sha256=JcKCCf0pDHy9rGeoenyn1Ivxsgqi9XYy6JpT5Z9SY00,213
+qualys_cli/audit.py,sha256=bKWNqHOfPZCLRZp5ujcsvO5uSxg74EMZjo-aIwqvHuI,21497
+qualys_cli/auth.py,sha256=3WI7RLhaD9OXWKCgEbE3B_oatalR9zOJ4-SaNpOHLpk,6906
+qualys_cli/cache.py,sha256=oMmh9P2eZQWxw_O-0_hZ5madyVh03RCFSIrSMLCGw0w,3604
+qualys_cli/cli.py,sha256=nrs0eYXPl0O_VelmhcVkSSceBpNzS4OQ8yoL6XJrZAs,45525
+qualys_cli/client.py,sha256=5uH6gFvmkI_S_YpRkHjzv4OuUFxu7wHY25PJW1oRftg,40875
+qualys_cli/config.py,sha256=lJhetjUyOa8YwmfROpK4zKxfHSQRO2mWdIXxz8vG6Xg,11568
+qualys_cli/extras.py,sha256=Z0vbLaZuXPLuatYTOv0BzwUzpr8ZdOTsiG149CwRarE,27923
+qualys_cli/flair.py,sha256=7FiYAVgznHsF2JRHBcBpZlNjg4Rq2SZvD4K68eQB3Mk,5461
+qualys_cli/formatters.py,sha256=BuckH033AO_q8pXwm5rZ0_Fvy_eikZa3ZGv3DNtWNTQ,31243
+qualys_cli/history.py,sha256=6pQx9O2Myl4LcV-kODzDTLIejZCkX_eABuyo-XTUv6Q,4378
+qualys_cli/http_server.py,sha256=7g4rkgGNE04D09oPE7Lj5kOUoVrUUM3fHnnx_N-FvO0,5890
+qualys_cli/mcp_server.py,sha256=VtHPs6Udvkh0FwsZLKXroI6wMWlFNa1xmowe1Omb9zM,12938
+qualys_cli/metrics.py,sha256=RU7gO7T39UEhVoShnvZH9rk4NY0dxTiWC7fdlhVP1Xw,3496
+qualys_cli/platforms.py,sha256=3e-YmLJHPI8oH4P9MCquho3596UcHKDwlDmtzgeTIqM,3224
+qualys_cli/queries.py,sha256=_Vphbhmeo4FI3muEF57rRBPJ2rFEbP03fTVCQ47_Qy8,4871
+qualys_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qualys_cli/commands/asset.py,sha256=KZOURVTpm0zIh2BD-TxKNKSCNvuE5_SwMAZKSjUdtdE,7002
+qualys_cli/commands/ca.py,sha256=QUHEuUGEWfUm-iLAfrMrjh4_gXR0AGV-Lpui_ROzIxQ,16885
+qualys_cli/commands/cs.py,sha256=txFb7kNz_zcM0JPcQ-hMNtzMpTjFhZo-QiQByrOcJ7c,18806
+qualys_cli/commands/csam.py,sha256=t27ju-oOSPYhHGYS9NzyBgI4ajFToKGHWGay44S8sUg,33081
+qualys_cli/commands/etm.py,sha256=JK-50daNN0TMzloVcKZHjVczqC4Y8Pa_yjkb5bRxuSw,7098
+qualys_cli/commands/pc.py,sha256=kY9EsLHsOMDN0u1ORaUfwdhwYtyTB_n4vjAsPgFoI-M,10672
+qualys_cli/commands/pm.py,sha256=fVV42coKPizkdEQF1kamJS3SU7dkkKFEWQElAAbB_UM,17349
+qualys_cli/commands/scanauth.py,sha256=qyH_y-mmyHzqadXQsgc8o6DUygU5lhKSkv_LpV-BfPI,12479
+qualys_cli/commands/sub.py,sha256=nduho5lb1IzbYtQh2boACEWu61eyrhzhtjVNR7p7ONU,6373
+qualys_cli/commands/tc.py,sha256=bjcnHZkNM_AvlAoX8xNn4Dh47OZmRA-2FaU7QIublPQ,22829
+qualys_cli/commands/user.py,sha256=JxiSZ2pLvlVN4EjTDKvNSHsmmUtgO8qnW_ghSeLMyCU,4299
+qualys_cli/commands/vm.py,sha256=ArbNywyoMxcQ_3daxOtJamHrI_lkmubXRPwZi7neIMI,23696
+qualys_cli/commands/was.py,sha256=0JK-hSDaArrQiqeo1c1E2xDICXvvChOmTPf5nypCA4c,50717
+qualys_cli-0.1.1.data/data/share/qualys-cli/docs/usage.html,sha256=drjMfohgWISQoPjiwBThftFXXUrNBxKen_WDT9Pjrtw,655941
+qualys_cli-0.1.1.dist-info/METADATA,sha256=PUdht3v-vDlx6i0Rb8nXGbpsQ8LbetwRPQJVrDVgin8,12563
+qualys_cli-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+qualys_cli-0.1.1.dist-info/entry_points.txt,sha256=TI_z7txhxW0GYPLixu797-w_-nQ_kCPdIjcuPogBp0A,51
+qualys_cli-0.1.1.dist-info/licenses/LICENSE,sha256=Vs-y16X1Kz8pxGJ9Uy54ykGaLME6hetRYI6wajCS7Zs,1080
+qualys_cli-0.1.1.dist-info/RECORD,,

qualys_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

qualys_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qualys-cli = qualys_cli.cli:main

qualys_cli-0.1.1.dist-info/licenses/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.