CISO Advisory

Decision-grade threat intelligence for CISOs and senior security leadership.

A terminal-first agent powered by Grok 4.5 (xAI) with live web search, X search, and code execution. It researches the current threat landscape (today, last 7 days, last 30 days) and writes a professional Markdown brief plus a modern, full-width HTML executive report.

Defensive use only. This tool supports security leadership and defenders. It does not provide exploit development guidance.

---

Features

Section	Purpose
Executive Snapshot	Top actions for the next 24–72 hours
High-Visibility Breaches	Who was hit, who attacked, how exploitation worked
Threat Landscape (7d / 30d)	Ransomware, malware, identity, cloud, APT notes
Malicious Libraries & Components	Exhaustive inventory — name, ecosystem, versions, malice type, actions
Critical Vulnerabilities	Active exploitation and prioritization
Underground & Leak Signals (OSINT)	Publicly reported underground / leak activity (no fabrications)
Foresight & Near-Term Signals	Early indicators for the next 2–6 weeks
CISO Control Checklist	Actionable controls tied to findings

Hard rule: no fabrications. Claims must be grounded in live tool research. Unverified items are omitted or labeled UNCONFIRMED / SIGNAL.

Outputs (local only)

File	Description
reports/ciso-brief-<date>-<window>-<timestamp>.md	Markdown brief
reports/ciso-brief-<date>-<window>-<timestamp>.html	Full-width modern HTML brief
reports/latest.md / latest.html	Always overwritten for daily workflows
reports/*-internal-sources.md	Optional private citation inventory (--internal-sources)

The public brief does not list raw source URLs (executive presentation). Use --internal-sources for your own verification trail. Generated reports are gitignored and should not be published.

---

Requirements

• Python 3.11+ (tested on 3.11–3.14)
• An xAI API key with access to Grok 4.5 and server-side tools
  → Create a key at console.x.ai
  → API docs: docs.x.ai

---

Quick start

git clone https://github.com/<YOUR_GITHUB_USER>/CISO_ADVISORY.git
cd CISO_ADVISORY

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -U pip
pip install .

cp .env.example .env
# Edit .env and set a real key:
# XAI_API_KEY=xai-...

ciso-brief doctor
ciso-brief run --open

Install note (Python 3.14)

Prefer pip install . (not pip install -e .). On Python 3.14, editable installs that write __editable__*.pth are skipped as “hidden,” which causes:

ModuleNotFoundError: No module named 'ciso_advisory'

After you change source code, run pip install . again (or use pip install -e . --config-settings editable_mode=compat if you need editable mode).

Alternative install

pip install -r requirements.txt
pip install .

---

Configuration

Copy the example env file and set your key:

cp .env.example .env

Variable	Required	Default	Description
XAI_API_KEY	Yes	—	xAI API key (console.x.ai)
XAI_MODEL	No	grok-4.5	Model id
XAI_MAX_TURNS	No	40	Standard tool-loop budget (hard max 200)
XAI_DEEP_MAX_TURNS	No	80	Budget when using --deep
AUTHOR_BYLINE	No	Prepared for executive security leadership	Report footer line
REPORTS_DIR	No	reports	Output directory

Never commit .env. It is gitignored. Only .env.example is tracked.

---

Usage

# Validate config (does not call the model beyond import checks)
ciso-brief doctor

# Full daily brief (7-day + 30-day)
ciso-brief run

# Open the HTML report when finished
ciso-brief run --open

# Deeper collection (more tool turns + ecosystem sweeps + gap-fill pass)
ciso-brief run --deep
ciso-brief run --deep --open

# Raise tool budget (hard max 200)
ciso-brief run --max-turns 100
ciso-brief run --deep --max-turns 120

# Emphasize a single window
ciso-brief run --window 7d
ciso-brief run --window 30d

# Sector / stack focus (still includes global criticals)
ciso-brief run --focus "finance, healthcare, SaaS"

# Private source inventory (local file; not for external sharing)
ciso-brief run --internal-sources

# Extra analyst instructions for this run
ciso-brief run --extra "Prioritize cloud identity and SSO abuse"

# Override as-of date (YYYY-MM-DD)
ciso-brief run --as-of 2026-07-25

Module form:

python -m ciso_advisory run --open

Going deeper

Lever	What it does	Cost / time
--deep	Higher tool budget (default 80), ecosystem-by-ecosystem package searches, second gap-fill pass	Higher
--max-turns N	Override tool-loop budget (8–200)	Scales with N
XAI_MAX_TURNS / XAI_DEEP_MAX_TURNS	Defaults in .env	Persistent
--extra "…"	Force extra themes	Low–medium
--focus "…"	Prioritize sector/stack	Low–medium
--window both	Full 7d + 30d (default)	Medium

Daily workflow (optional)

# Example: weekdays 07:30 local
30 7 * * 1-5 cd /path/to/CISO_ADVISORY && .venv/bin/ciso-brief run --window both

Open reports/latest.html each morning.

---

Architecture

• SDK: official xai-sdk (not a thin OpenAI-only wrapper for tools)
• Model: grok-4.5
• Server-side tools: web_search, x_search, code_execution
• Outputs: sanitized HTML + Markdown under reports/

CISO_ADVISORY/
├── .env.example              # template only — no secrets
├── .github/workflows/ci.yml  # pytest + CLI smoke
├── LICENSE                   # MIT
├── SECURITY.md               # threat model & controls
├── CONTRIBUTING.md
├── pyproject.toml
├── requirements.txt
├── reports/                  # runtime output (gitignored content)
├── scripts/smoke_report.py   # offline HTML render smoke (no API)
├── tests/test_security.py
└── src/ciso_advisory/
    ├── agent.py              # Grok session + tools
    ├── cli.py                # ciso-brief
    ├── config.py
    ├── prompts.py
    ├── report.py
    ├── security.py           # sanitization, scrubbing, path guards
    └── templates/brief.html.j2

---

Security

Hardened for local CLI use:

• HTML sanitization of model output (nh3) before report embedding
• Secret scrubbing (API-key-like patterns) before write / error display
• Reports path confinement + safe filenames
• Input length limits and max-turns hard cap
• API key never printed by doctor
• Content-Security-Policy on HTML reports

Details: SECURITY.md.

Pre-publish checklist (maintainers)

• No .env in the tree to be committed
• No real keys in source, tests, or docs
• reports/* empty of generated briefs (only .gitkeep / README.md)
• git status does not list .venv, build/, or __pycache__
• pytest tests/ -v passes
• Repository is public only after the above

---

Cost & runtime

Each run uses multi-step tool calling (web + X + reasoning). Expect:

• Several minutes for a standard brief; longer with --deep
• Token + tool charges per xAI pricing

---

Development & tests

pip install ".[dev]"
pytest tests/ -v
python scripts/smoke_report.py   # offline report render only

CI runs on push/PR via GitHub Actions (Python 3.11–3.13).

---

Disclaimer

This tool supports defensive security decision-making. Intelligence is only as current as public sources available at generation time and may be incomplete or wrong. Always corroborate high-impact actions with internal telemetry, vendor advisories, and your incident processes. The authors provide no warranty of fitness for a particular purpose.

---

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md.