From dafbdf8482d0994ee7b597556e7ac50cdd33b91f Mon Sep 17 00:00:00 2001 From: Ali Bahaloo Date: Tue, 28 Jul 2026 16:49:27 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20describe=20the=20tool=20by=20what=20it?= =?UTF-8?q?=20does=20=E2=80=94=20check=20an=20advisory=20bundle?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The description still read "Fleet-wide firewall impact analysis, straight from Cisco", written before the bundle check existed. Both ledes described only the device-by-device sweep, so the workflow the tool is actually for — hand it a Cisco Event Response link, learn which of your devices and releases that publication impacts — was invisible until deep into "Run it". New description, applied to all nine places one lives: Check a Cisco advisory bundle against your firewall inventory Four shared the old literal (README, docs/index.html, pyproject, the banner slogan); the rest are the meta description, both ledes, --help, and the package docstring. "Run it" is restructured so the bundle prompt is the flow, with --erp for scheduling right after it. Two gaps this turned up, both worth more than the wording: - --erp was missing from the README's automation flag table. That absence is why it looked like the flag did not exist at all. Added, with a runnable scheduled-review example, and the exit-codes line now covers the bundle failures (2 for a value that is not a bundle address, 1 for unreachable or a page yielding no advisories, no report written either way). - sec.cloudapps.cisco.com was absent from the network prerequisites in both files and from the "Could not reach Cisco" troubleshooting entry. A user behind a corporate proxy would have been blocked on the bundle fetch with nothing in the docs explaining why. The whole-inventory report keeps a short note at the end of "Run it" rather than equal billing. It still works, so hiding it would misdescribe the tool in the other direction, but it is no longer what the tool announces itself as. "Fleet" survives in three places deliberately: the two disclaimers, where the strong word is doing real work, and the uninstall example, which is about machines rather than firewalls. No VERSION bump: docs and packaging metadata only, matching f78ca51, e156578 and 73de536 — e156578 changed a pyproject field, the same category as this. Co-Authored-By: Claude Opus 5 --- README.md | 87 ++++++++++++++++++++++++++++-------------------- caia/__init__.py | 2 +- caia/cli.py | 5 +-- caia/ui.py | 2 +- docs/index.html | 20 ++++++----- pyproject.toml | 2 +- 6 files changed, 68 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 1b4bb33..8439416 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,18 @@

Cisco Advisory Impact Analyzer

-

Fleet-wide firewall impact analysis, straight from Cisco

+

Check a Cisco advisory bundle against your firewall inventory

--- -Run one command in the folder holding your firewall inventory and get back an HTML report -telling you **which of your firewalls Cisco lists as vulnerable, and to what**. +Cisco publishes firewall vulnerabilities in **bundles** — an Event Response page listing every +advisory released that day. Give this tool the link to one and it tells you **which of your +firewalls and software releases that publication impacts**, and the release that fixes each. It asks Cisco's **PSIRT advisory API** — the same published data behind Cisco's public -Software Checker — which advisories apply to each firewall's software release on its exact -hardware model, and reports the answer. Every verdict comes from Cisco; nothing is inferred. +Software Checker — which of the bundle's advisories apply to each firewall's software release +on its exact hardware model. Every verdict comes from Cisco; nothing is inferred, and a +firewall it could not check is never reported as safe. Installed as a **[uv](https://docs.astral.sh/uv/) tool**: one install command, then a single `caia` command you can run from any folder. Works on **macOS, @@ -29,7 +31,7 @@ Windows, and Linux**. | 2 | **Git** | The uv install command below pulls the tool straight from GitHub, so Git must be installed first. Not sure if you have it? See [Get Git](#get-git) below. | | 3 | **Cisco PSIRT API credentials** | A client ID and client secret from — each person needs their own (steps below). | | 4 | **Your firewall inventory** as an Excel `.xlsx` file in the folder you run from | You build this yourself (format below). | -| 5 | **Internet access** to `apix.cisco.com` and `id.cisco.com` | Usually already available; corporate proxies can block these. | +| 5 | **Internet access** to `apix.cisco.com`, `id.cisco.com` and `sec.cloudapps.cisco.com` | The first two are Cisco's advisory API and its token endpoint; the third serves the bundle page. Usually already available; corporate proxies can block these. | > Your credentials are stored once, per user, via `caia --config`. The tool refuses to run > without them and points you at `--config`. @@ -202,47 +204,49 @@ on it behaves exactly like the uv install — use it as described in [Run it](#r caia ``` -The tool finds your inventory in that folder (if there's more than one candidate, it lists them -and lets you pick), asks whether you want to scope the report to one Cisco advisory bundle -(press **Enter** to skip), asks Cisco which published advisories apply to each firewall's -software release on its exact hardware model, and writes -**`impact_report__