# ibm/itbench-ciso-caa-agent architecture

> Architecture diagram of the GitHub repository ibm/itbench-ciso-caa-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibm/itbench-ciso-caa-agent
- Repository: https://github.com/ibm/itbench-ciso-caa-agent

## Overview

##### Project Type and Purpose
- This is a full-stack automation agent tool (CISO Agent) for compliance assessments in Kubernetes/RHEL environments.
- It uses LLMs to generate policies (Kyverno, OPA Rego), orchestrate evidence collection, integrate with GitOps, and deploy/fix policies automatically.
- Built on top of Python, Docker/Podman, and open-source frameworks CrewAI and LangGraph.

##### File Structure Analysis
- Top level: configuration files (.flake8, .gitignore, Dockerfile, pyproject.toml, requirements-dev.txt), build/deployment artifacts (Dockerfile, agent-harness.yaml), documentation (README.md, langtrace.md, img/)
- src/ciso_agent/ – core code:
- main.py: entrypoint for the agent container
- manager.py: orchestrates the overall workflow
- llm.py: LLM interface (wrapper around CrewAI/LangGraph)
- agents/: concrete agents for various scenarios (kubernetes_kubectl_opa.py, kubernetes_kyverno.py, rhel_playbook_opa.py, etc.)
- tools/: helper modules to generate/run policies and playbooks (generate_*.py, run_*.py, utils.py)
- tests/: unit tests for llm and model abstractions

##### Key Architecture Insights from README
- The agent runs as a container, mounts an environment (.env) and a workdir containing cluster credentials/inventory.
- It reads a “goal” (natural language scenario), then invokes the LLM to plan steps, generates policy artifacts, deploys them, collects results, iterates until success.
- Supports multiple LLM backends (OpenAI-compatible, IBM watsonx.ai, Azure) via environment configuration.
- Integrates with external systems: Kubernetes (via kubectl), Ansible playbooks (RHEL).

a. Main Components
- User / CLI: invokes the agent container with goal, workdir, .env
- Containerized CISO Agent:
- Entrypoint (main.py)
- Manager (workflow coordinator)
- LLM Interface (llm.py with CrewAI/LangGraph)
- Policy Agents (kubernetes_kubectl_opa, kubernetes_kyverno, rhel_playbook_opa)
- Tools Module (generate_*, run_*, utils)
- External Services/Systems:
- LLM Provider (OpenAI, WatsonX, Azure)
- Kubernetes API Server (kubectl)
- RHEL Host via Ansible (inventory.ansible.ini -> ansible-playbook)
- GitOps Repository (optional, for policy deployment)
b. Relationships & Data Flow
1. User/CLI → Container: passes .env, workdir, goal text
2. main.py → Manager: initializes environment, loads goal
3. Manager ↔ llm.py: sends goal & context, receives plan/next steps
4. Manager → Agents: for each step, calls appropriate agent module
5. Agent → Tools (generate_*.py): produce policy or playbook artifacts
6. Agent → Tools (run_*.py): invoke kubectl/OPA CLI or ansible-playbook against target env
7. Tools ↔ External System: run commands, collect responses (success/failure, logs)
8. Manager loops until goal achieved, then outputs result
c. Architectural Patterns & Principles
- Modular design: clear separation between orchestration (manager), LLM interface, agent implementations, and tool adapters.
- Plugin-style agents: each “agents/” file implements a scenario adapter.
- Environment-agnostic LLM integration: llm.py abstracts provider details via .env.
- Containerized deployment: all components run in a single Docker/Podman container, relying on mounted volumes for input.
d. Key Technologies/Frameworks
- Python 3.11 (pyproject.toml)
- LLM frameworks: CrewAI, LangGraph
- Docker/Podman for containerization
- kubectl, OPA CLI, Ansible for policy deployment & compliance checks
- YAML for scenario harness (agent-harness.yaml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    UserCLI["User/CLI"]:::external -->|".env, workdir, goal"| Entrypoint["Entrypoint\n(main.py)"]:::orchestration

    subgraph "CISO Agent Container"
        subgraph "Orchestration Layer"
            Entrypoint --> Manager["Workflow Manager\n(manager.py)"]:::orchestration
        end
        subgraph "AI/LLM Layer"
            LLMInt["LLM Interface\n(llm.py)"]:::ai
        end
        subgraph "Domain Agents"
            KOpa["K8s OPA Agent\n(kubernetes_kubectl_opa.py)"]:::agent
            KKyverno["K8s Kyverno Agent\n(kubernetes_kyverno.py)"]:::agent
            UKyverno["K8s Kyverno Update Agent\n(kubernetes_kyverno_update.py)"]:::agent
            RPlay["RHEL Playbook OPA Agent\n(rhel_playbook_opa.py)"]:::agent
        end
        subgraph "Tool Modules"
            GenKyverno["Kyverno Policy Generator\n(generate_kyverno.py)"]:::tool
            GenOPA["OPA Rego Policy Generator\n(generate_opa_rego.py)"]:::tool
            GenPB["Ansible Playbook Generator\n(generate_playbook.py)"]:::tool
            RunKube["Kubectl Runner\n(run_kubectl.py)"]:::tool
            RunOPA["OPA Rego Runner\n(run_opa_rego.py)"]:::tool
            RunPB["Playbook Runner\n(run_playbook.py)"]:::tool
            Utils["Shared Utilities\n(utils.py)"]:::tool
        end

        Manager -->|"plan() / execute step"| LLMInt
        LLMInt -->|"API Calls"| LLMService["LLM Service"]:::external
        LLMService -->|"response"| LLMInt
        LLMInt -->|"plan response"| Manager

        Manager -->|"execute step"| KOpa
        Manager -->|"execute step"| KKyverno
        Manager -->|"execute step"| UKyverno
        Manager -->|"execute step"| RPlay

        KOpa -->|"generate_policy()"| GenOPA
        KKyverno -->|"generate_policy()"| GenKyverno
        UKyverno -->|"generate_policy()"| GenKyverno
        RPlay -->|"generate_playbook()"| GenPB

        GenOPA -->|"artifact"| RunOPA
        GenKyverno -->|"artifact"| RunKube
        GenPB -->|"artifact"| RunPB

        RunKube -->|"kubectl apply"| KubeAPI["Kubernetes API"]:::external
        RunOPA -->|"opa eval"| KubeAPI
        RunPB -->|"ansible-playbook"| RHELHost["RHEL Host/Ansible"]:::external

        KubeAPI -->|"response"| RunKube
        KubeAPI -->|"response"| RunOPA
        RHELHost -->|"response"| RunPB

        RunKube -->|"result"| Manager
        RunOPA -->|"result"| Manager
        RunPB -->|"result"| Manager
    end

    Dockerfile["Container Definition\n(Dockerfile)"]:::external
    agentHarness["Scenario Harness Config\n(agent-harness.yaml)"]:::external
    Dockerfile -.-> Entrypoint
    agentHarness -.-> Entrypoint

    subgraph "Unit Tests"
        TestLLM["LLM Unit Tests\n(tests/test_llm.py)"]:::external
        TestModels["Model Unit Tests\n(tests/test_models.py)"]:::external
    end

    click Entrypoint "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/main.py"
    click Manager "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/manager.py"
    click LLMInt "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/llm.py"
    click KOpa "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/agents/kubernetes_kubectl_opa.py"
    click KKyverno "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/agents/kubernetes_kyverno.py"
    click UKyverno "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/agents/kubernetes_kyverno_update.py"
    click RPlay "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/agents/rhel_playbook_opa.py"
    click GenKyverno "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/tools/generate_kyverno.py"
    click GenOPA "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/tools/generate_opa_rego.py"
    click GenPB "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/tools/generate_playbook.py"
    click RunKube "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/tools/run_kubectl.py"
    click RunOPA "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/tools/run_opa_rego.py"
    click RunPB "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/tools/run_playbook.py"
    click Utils "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/src/ciso_agent/tools/utils.py"
    click Dockerfile "https://github.com/ibm/itbench-ciso-caa-agent/tree/main/Dockerfile"
    click agentHarness "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/agent-harness.yaml"
    click TestLLM "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/tests/test_llm.py"
    click TestModels "https://github.com/ibm/itbench-ciso-caa-agent/blob/main/tests/test_models.py"

    classDef orchestration fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef ai fill:#e2ccff,stroke:#5e00cc,stroke-width:1px
    classDef agent fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef tool fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:1px
```
