santosomar/AI-agents-for-cybersecurity

How to use it

Requirements: Python 3.13+ and uv. One script runs offline as a smoke test. Most others need an OpenAI key:

uv sync --python python3.13
uv run python part1_foundational_topics/huggingface_example.py
export OPENAI_API_KEY="your-key-here"

A local .env file also works and is already gitignored. Each part maps to a training module or book chapter, and the scripts stand alone, so you can go straight to the part you need. If a book or recording disagrees with the repository, the repository is the current version.

Useful entry points by goal:

• RAG on security data:
• part4_rag_examples/basic_rag_part1.py through part3.py cover the Chroma store, persistence and an end-to-end LCEL chain.
• text_splitting_deep_dive.py compares character, sentence, token and recursive splitting.
• embedding_deep_dive.py compares OpenAI and Hugging Face embeddings.
• utils/embedding_cost_calculator.py estimates embedding cost.
• The part also links the WFGY 16 Problem Map, a checklist of RAG and long-context failure modes with mitigations.
• Local models: part1_foundational_topics/ollama/ covers streaming and multimodal use. Part 1 also ships 1,000 CVE embeddings with metadata for TensorFlow Embedding Projector.
• Agent patterns to copy:
• asm_example/ is a LangGraph recon → scan → analysis → report flow.
• crewai_example/ is a vulnerability-management crew with nmap and CVE tools.
• deepagents_example/ is a SOC agent with planning and subagents.
• mcp_servers_examples/ holds the FastMCP servers and client agents.
• Cost control (Part 7), numbered scripts:
• 01_context_growth.py argues agent cost grows with the square of task length and shows how compaction bends the curve.
• 04_cost_per_outcome.py computes (model + runtime + human review) ÷ acceptance rate.
• 05_model_routing.py covers routers and cascades, including the "escalation trap".
• 06_tool_schema_overhead.py measures tool-schema token overhead.
• 07_token_budget_guard.py sets per-task token, cost and loop ceilings as a denial-of-wallet defence.
• 08_batch_triage.py runs offline triage through the Batch API at half price.
• 03_live_cache_check.py checks prompt-cache hits against a live provider.
• docs/07_cyber_index.md uses a cost-aware defensive benchmark to choose models.
• Framework selection (Part 6): an overview with a side-by-side comparison, a "which one for which job" guide, a map of 2026 CVEs and supply-chain incidents affecting these frameworks, and hardening notes for each.

How it works (Part 8 harness spec)

Part 8 is documents only, with no code. Start with part8_multi-agent_harness_spec/README.md.

• safety-governance.md explicitly overrides any implementation choice. It defines a scope manifest, approval gates G0–G3, lab isolation, budgets, an append-only audit log and a kill switch.
• architecture.md describes a supervisor, a planner and narrow workers. They share an evidence store, exchange A2A-style task messages and reach tools through MCP brokers that deny by default.
• agents.yaml encodes capabilities, gates and hard-stop triggers.

flowchart LR
  R[Reconnaissance] --> V[Vuln discovery]
  V --> G{Human approval<br/>per execution?}
  G -- yes --> E[Exploitation validation]
  E --> G2{Human approval?}
  G2 -- yes --> P[Post-exploitation impact]
  G -- no --> M[Remediation<br/>recommendations only]
  G2 -- no --> M
  P --> M

Exploitation validation and post-exploitation impact are off by default. Each run needs a recorded, task-specific human approval for a named lab target. The design is modelled on Cisco DevNet's Foundry Security Spec, and the research behind it dates from October 2026.

Limits

• Most labs are not free to run. Everything beyond the smoke test assumes a paid OpenAI key. Ollama and Hugging Face appear only in specific Part 1 examples.
• Some examples act on real systems: nmap scanning, Agent Zero (which runs in its own Kali Linux container), the ASM workflow and the ethical-hacking LangGraph agent. Run them only against systems you own or are authorised to test, ideally in an isolated lab.
• Part 8 gives you nothing to execute. Any implementation would be yours to build and validate.
• No licence is stated in the fetched text. Check the repository before reusing code.
• Expect drift. The repository is updated continuously, so file names and behaviour may change.
• Security reports about the repository go privately via SECURITY.md, not as public issues.