# Aegis AI - Transparency and Training Guide

## Table of Contents

1. [Introduction](#introduction)
2. [AI Functionality Disclosure](#ai-functionality-disclosure)
3. [How Aegis Uses AI](#how-aegis-uses-ai)
4. [Agent Architecture](#agent-architecture)
5. [AI Model Information](#ai-model-information)
6. [Data Handling and Privacy](#data-handling-and-privacy)
7. [User Training Requirements](#user-training-requirements)
8. [Appropriate Use Guidelines](#appropriate-use-guidelines)
9. [Human Review Requirements](#human-review-requirements)
10. [Limitations and Risks](#limitations-and-risks)
11. [Contact and Support](#contact-and-support)

---

## Introduction

This document provides transparency about Aegis AI's use of artificial intelligence, outlines user training requirements, and establishes guidelines for appropriate use of the tool. All users of Aegis AI should read and understand this document before using the tool.

### Purpose

This transparency document serves to:

- Disclose the use of AI functionality in Aegis
- Explain how AI is used in the tool
- Provide training guidance for users
- Establish appropriate use guidelines
- Ensure users understand limitations and requirements

---

## AI Functionality Disclosure

### Notice of AI Usage

**Aegis AI uses Generative Artificial Intelligence (Large Language Models) to perform security analysis tasks.**

This means:

- **AI-Generated Content:** All suggestions, assessments, and analyses are generated by AI models
- **Probabilistic Outputs:** Results may vary between runs and are not deterministic
- **Requires Human Review:** All AI outputs must be reviewed by qualified human experts
- **Not a Replacement:** AI assists but does not replace human security expertise

### Where AI is Used

Aegis uses AI in the following areas:

1. **CVE Impact Assessment:** AI analyzes CVE data to suggest impact levels and CVSS scores
2. **CWE Classification:** AI maps CVEs to Common Weakness Enumeration identifiers
3. **Text Generation:** AI suggests improvements to security descriptions and statements
4. **PII Detection:** AI identifies potentially sensitive information in security texts
5. **Score Explanation:** AI explains differences between CVSS scores
6. **Component Intelligence:** AI gathers and synthesizes information about software components

### AI Model Providers

Aegis supports multiple AI model providers:

- **Google Gemini** (cloud-based)
- **Anthropic Claude** (cloud-based)
- **OpenAI ChatGPT** (cloud-based)
- **Local Models** (Ollama, custom models)

**Important:** The specific model used depends on your configuration. See [Configuration Guide](env-vars.md) for details.

---

## How Aegis Uses AI

### Autonomous Agent Architecture

Aegis uses **autonomous AI agents** that:

1. **Receive User Queries:** Users request analysis (e.g., "assess CVE-2025-0725")
2. **Gather Context:** Agents autonomously decide which tools to use to gather information
3. **Retrieve Data:** Agents query security databases (OSIDB, NVD, CWE, etc.)
4. **Generate Analysis:** AI models process context and generate structured responses
5. **Return Results:** Users receive AI-generated suggestions with explanations

### Tool Integration

AI agents use various tools to gather context. Tools can be enabled/disabled via environment variables (see [env-vars.md](env-vars.md)).

> **⚠️ Embargoed Data Security:** External tools (Wikipedia, GitHub, Tavily, PyPI) are **disabled by default** to prevent potential leakage of embargoed CVE data to third-party services. The Red Hat profile has access to OSIDB which may contain embargoed CVEs. Enable external tools only when processing public CVE data, or ensure you're using a secure/local LLM model. Additionally, embargoed CVE retrieval from OSIDB is blocked by default (`AEGIS_OSIDB_RETRIEVE_EMBARGOED=false`) as an extra safeguard.

#### Security Databases

- **OSIDB:** Red Hat internal security database providing CVE metadata, CVSS scores, component information, affected products, comments, and references (Red Hat profile only)
- **OSV.dev:** Open Source Vulnerabilities database for vulnerability information across multiple ecosystems (enabled by default for public profile)
- **CWE (Common Weakness Enumeration):** MITRE CWE database for weakness classification, definitions, and semantic search (enabled by default via `AEGIS_USE_CWE_TOOL_CONTEXT`)
- **NVD (National Vulnerability Database):** NIST's public CVE database accessed via MCP server (`mcp-nvd`) for authoritative CVE information and CVSS scores (optional, requires `NVD_API_KEY`)
- **CISA KEV:** CISA Known Exploited Vulnerabilities catalog to identify actively exploited CVEs (optional via `AEGIS_USE_CISA_KEV_TOOL_CONTEXT`)

#### Component Repositories

- **GitHub:** Source code repositories accessed via MCP server (`github-mcp-server`) to retrieve vulnerability references, patches, and component information (optional via `AEGIS_USE_GITHUB_MCP_TOOL_CONTEXT`, requires `GITHUB_PERSONAL_ACCESS_TOKEN`)
- **Linux Kernel CVEs:** Git repository (`git.kernel.org/pub/scm/linux/security/vulns.git`) for kernel-specific CVE metadata, commit hashes, and affected files (optional via `AEGIS_USE_LINUX_CVE_TOOL_CONTEXT`)
- **PyPI:** Python Package Index accessed via MCP server (`mcp-pypi`) for Python component information (optional via `AEGIS_USE_PYPI_MCP_CONTEXT`)
- **Wikipedia:** General encyclopedic information about software components (optional via `AEGIS_USE_WIKIPEDIA_TOOL_CONTEXT` or `AEGIS_USE_WIKIPEDIA_MCP_CONTEXT`)

#### Additional Context Sources

- **Tavily:** Web search engine for retrieving current information from vulnerability references and security advisories (optional via `AEGIS_USE_TAVILY_TOOL_CONTEXT`, requires `TAVILY_API_KEY`)

### Context Enrichment (RAG)

The AI does not rely solely on its training data. Instead, it:

- Retrieves real-time data from security databases (OSIDB, NVD, CISA KEV, OSV.dev)
- Accesses current CVE information including titles, descriptions, CVSS scores, and impact assessments
- Queries component repositories (GitHub, Linux kernel CVE repo, PyPI) for patches, commits, and component metadata
- Gathers relevant security context including:
  - **CVE Metadata:** Title, description, impact level, CVSS vectors and scores
  - **Component Information:** Affected components, versions, and product mappings
  - **Vulnerability References:** URLs to advisories, patches, and related security information
  - **CWE Classifications:** Weakness types and definitions for vulnerability taxonomy
  - **Exploit Status:** Whether the CVE is known to be actively exploited (CISA KEV)
  - **Kernel-Specific Context:** Commit hashes, affected files, and patch information for Linux kernel CVEs
  - **Product-Specific Context:** Red Hat product affects, impact assessments, and internal comments

This approach (Retrieval Augmented Generation - RAG) helps ensure more accurate and current analysis by augmenting the AI's training data with real-time, authoritative security information.

---

## Agent Architecture

### How Agents Autonomously Decide Which Tools to Use

Aegis uses **autonomous AI agents** that dynamically decide which tools to call based on:

1. The toolsets attached to the agent
2. The prompt instructions and rules provided
3. The context of the task
4. The LLM's autonomous decision-making capabilities

### Agent Configuration

Agents are created with toolsets that provide access to various tools. Different agents have different tool access:

```python
# this object is only used by CLI
simple_agent = create_aegis_agent(
    name="SimpleAgent",
    output_type=AegisAnswer,
)

# Red Hat feature agent (has access to internal OSIDB tools)
rh_feature_agent = create_aegis_agent(
    name="RHFeatureAgent",
    retries=agent_default_max_retries,
    toolsets=[redhat_cve_toolset, public_toolset],
)

# Public feature agent (only public tools)
public_feature_agent = create_aegis_agent(
    name="PublicFeatureAgent",
    retries=agent_default_max_retries,
    toolsets=[public_cve_toolset, public_toolset],
)

```

### Prompt-Guided Tool Selection

The `AegisPrompt` class includes `rules` that guide the agent on which tools to use. These rules are embedded in the prompt sent to the LLM.

**Example: SuggestCWE Feature rules:**

```python
rules="""
    - When CVE component is kernel always use kernel_cve tool to retrieve additional context.
    - Retrieve and summarise additional context strictly from vulnerability reference URLs and CWE tool outputs.
        - Prefer mitre_cwe tools (retrieve_allowed_cwe_ids, search_cwes, retrieve_cwes) for CWE selection and definitions.
        - Use github mcp tool to resolve vulnerability reference URLs if present.
        - Avoid using general-purpose web search or encyclopedic tools for CWE selection unless references are insufficient.
    - Identify set of candidate CWEs - always use the mitre cwe tool retrieve_allowed_cwe_ids to filter candidate CWE list.
        - Analyze vulnerability, identify CWE that matches root cause of weakness, being careful about memory management and buffer overflows.
        - Perform search using mitre cwe tool cwe_searches to identify candidate CWEs (perform cwe_searches with 2-3 different queries).
    - Use mitre cwe retrieve_cwes tool to get additional information on candidate CWEs.
    - Select the top 2-3 most applicable CWEs (preference on applicability and higher similarity score) from the final set of candidate CWEs.
    - The final list of suggested CWEs should be ranked from most to least applicable to the vulnerability. For example, the first item in the array should be the most applicable CWE based on entire vulnerability analysis.
    Output should include:
    - cwe: Return ordered list of top 2–3 applicable CWE IDs (ex. ["CWE-94"])
    - explanation: 1–2 sentences connecting CVE details to the CWE.
    - confidence: [0.00..1.00].
    ...
"""
```

### How Autonomy Works

The autonomy comes from the combination of:

1. **Tool Availability:** Toolsets attached to agents provide a catalog of available tools
2. **Prompt Guidance:** Rules in the prompt suggest which tools to use and when
3. **LLM Decision-Making:** The LLM model itself decides which tools to call based on the prompt and context
4. **Framework Support:** The pydantic-ai framework handles the tool calling mechanism

The agent is **not pre-programmed** with a fixed sequence of tool calls. Instead, it makes **dynamic decisions** based on:

- The specific task at hand
- The context provided
- The prompt instructions
- The available tools

### Example Flow

1. **User Request:** "Assess CVE-2025-0725"
2. **Feature Execution:** `SuggestImpact` feature is called
3. **Prompt Creation:** An `AegisPrompt` is created with instructions, rules, and context
4. **Agent Run:** The agent receives the prompt and has access to toolsets
5. **Autonomous Tool Calls:** The LLM decides to:
   - Call `osidb_flaw_tool` to get CVE details
   - Call `kernel_cve_tool` (if kernel-related)
   - Call `cisa_kev_tool` to check for known exploits
   - Call `github` MCP tools to resolve reference URLs
6. **Result:** The agent returns analysis with CVSS score and impact

### Key Source Files

- **Agent Configuration:** `src/aegis_ai/agents/__init__.py`
- **Tool Registration:** `src/aegis_ai/toolsets/__init__.py`
- **Prompt Structure:** `src/aegis_ai/prompt.py`
- **Feature Implementation:** `src/aegis_ai/features/cve/__init__.py`
- **Feature Base Class:** `src/aegis_ai/features/__init__.py`

---

## AI Model Information

### Supported Models

Aegis can work with various LLM models. The model you use depends on your configuration:

#### Cloud-Based Models

- **Google Gemini:** `gemini-2.5-flash`, `gemini-2.0-flash-exp`
- **Anthropic Claude:** `claude-3-5-sonnet-latest`, `claude-3-opus-latest`
- **OpenAI:** `gpt-4`, `gpt-3.5-turbo`

#### Local Models

- **Ollama Models:** Any model supported by Ollama (e.g., `llama3.2:3b`)
- **Custom Models:** Any model compatible with the configured API

### Model Selection Guidelines

**For Public/Non-Sensitive Data:**
- Cloud-based models (Gemini, Claude, ChatGPT) are suitable
- Faster response times
- Access to latest model capabilities

**For Internal/Embargoed Data:**
- Use enterprise/private models or local models
- Ensures data privacy
- Prevents data leakage to third parties

**For Classified Data:**
- **Only use local models**
- No data leaves your environment
- Maximum security and control

### Model Capabilities

AI models used by Aegis support:

- **Structured Output:** Generate JSON responses matching defined schemas
- **Tool Calling:** Autonomously invoke tools to gather context
- **Reasoning:** Analyze complex security scenarios
- **Natural Language:** Process and generate human-readable explanations

### Model Limitations

All AI models have limitations:

- **Training Data Cutoff:** Models may not know about very recent CVEs
- **Hallucination:** Models may generate plausible but incorrect information
- **Bias:** Models may reflect biases in training data
- **Context Limits:** Models have token limits that may truncate context
- **Probabilistic:** Outputs are not deterministic

---

## Data Handling and Privacy

### Data Sent to AI Models

When you use Aegis, the following data may be sent to AI models:

- **CVE Identifiers:** CVE IDs you request analysis for
- **CVE Metadata:** Titles, descriptions, and related information
- **Component Names:** Software component names you query
- **Context Data:** Information retrieved from security databases
- **Your Queries:** The specific analysis requests you make

### Data Retention

**Cloud-Based Models:**
- Check your LLM provider's data retention policies
- Some providers may log and retain API requests
- Review provider privacy policies before use

**Local Models:**
- No data leaves your environment
- Complete data privacy
- No third-party logging

### Data Classification

**Match model selection to data classification:**

| Data Classification | Model Type | Example |
|---------------------|------------|---------|
| Public CVE data | Cloud models | Gemini, Claude |
| Internal/Embargoed | Private/Local | Enterprise models, Ollama |
| Classified | Local only | Local Ollama instance |

### Security Considerations

1. **API Keys:** Protect API keys - never commit to version control
2. **Network Security:** Use HTTPS for all API connections
3. **Access Control:** Implement proper authentication and authorization
4. **Audit Logging:** Log AI usage for compliance and review
5. **Data Minimization:** Only send necessary data to AI models

---

## User Training Requirements

### Required Training

All users of Aegis AI must:

1. **Read this Transparency Document** - Understand AI usage and limitations
2. **Complete User Guide Review** - Read [USER_GUIDE.md](USER_GUIDE.md)
3. **Understand Disclaimers** - Know that AI outputs require human review
4. **Learn Best Practices** - Follow guidelines for appropriate use

### Training Topics

#### 1. Understanding AI Limitations

Users must understand:

- AI generates probabilistic outputs
- Results may vary between runs
- AI can make mistakes or "hallucinate"
- AI suggestions are starting points, not final answers

#### 2. Human Review Requirements

Users must know:

- **All AI outputs require human expert review**
- Never use AI suggestions without validation
- Cross-reference with authoritative sources
- Document review decisions

#### 3. Appropriate Data Handling

Users must:

- Match model selection to data classification
- Never send classified data to public cloud models
- Understand data retention policies
- Follow organizational data handling policies

#### 4. Tool Capabilities

Users should understand:

- What each feature does
- When to use each feature
- How to interpret results
- How to provide feedback

### Documentation

- [User Guide](USER_GUIDE.md) - Comprehensive user documentation
- [OpenAPI Specification](openapi.yml) - API documentation with feature details

---

## Appropriate Use Guidelines

### ✅ Appropriate Uses

Aegis AI is appropriate for:

1. **Initial Triage:** Quick assessment to prioritize CVEs
2. **Draft Generation:** Creating initial drafts of security text
3. **Research Assistance:** Gathering context about components and CVEs
4. **Pattern Recognition:** Identifying common vulnerability patterns
5. **Documentation:** Generating explanations and rationales
6. **Learning:** Understanding security concepts and relationships

### ❌ Inappropriate Uses

Aegis AI should NOT be used for:

1. **Final Decisions:** Making final security decisions without human review
2. **Classified Data:** Sending classified data to public cloud models
3. **Automated Publishing:** Automatically publishing AI-generated content
4. **Replacement of Expertise:** Replacing human security expertise
5. **Compliance Claims:** Using AI outputs to claim regulatory compliance without validation
6. **Sensitive PII:** Processing highly sensitive PII without proper safeguards

### Best Practices

1. **Always Review:** Never use AI outputs without human review
2. **Validate Sources:** Cross-reference with authoritative security databases
3. **Document Decisions:** Record why you accepted or rejected AI suggestions
4. **Provide Feedback:** Submit feedback to improve the tool
5. **Stay Informed:** Keep up with updates and changes to the tool
6. **Follow Policies:** Adhere to your organization's AI usage policies

---

## Human Review Requirements

### Mandatory Review

**ALL AI-generated outputs from Aegis MUST be reviewed by qualified human security experts before use.**

### Review Checklist

When reviewing AI outputs, verify:

- [ ] **Accuracy:** Is the information factually correct?
- [ ] **Completeness:** Is all necessary information present?
- [ ] **Context:** Does the analysis consider all relevant factors?
- [ ] **Consistency:** Does it align with organizational standards?
- [ ] **Appropriateness:** Is it suitable for the intended audience?
- [ ] **Compliance:** Does it meet regulatory and policy requirements?

### Review Process

1. **Initial Review:** Quickly assess if the suggestion is reasonable
2. **Source Verification:** Check against authoritative sources
3. **Context Validation:** Ensure all relevant context was considered
4. **Expert Consultation:** Consult with subject matter experts if needed
5. **Decision Documentation:** Record your acceptance, modification, or rejection
6. **Feedback Submission:** Provide feedback to improve the tool

### When to Reject AI Suggestions

Reject AI suggestions when:

- Information is factually incorrect
- Critical context is missing
- Analysis doesn't match your organization's assessment
- Output doesn't meet quality standards
- Compliance or policy requirements aren't met

### Documentation Requirements

Document:

- Whether you accepted, modified, or rejected the suggestion
- Reasons for your decision
- Any modifications made
- Sources consulted for validation
- Expert consultations (if any)

---

## Limitations and Risks

### Known Limitations

1. **AI Hallucination:** AI may generate plausible but incorrect information
2. **Context Gaps:** AI may miss important context not in its training or retrieved data
3. **Bias:** AI models may reflect biases in training data
4. **Version Differences:** Different model versions may produce different results
5. **Tool Availability:** Results depend on availability of external tools and databases
6. **Token Limits:** Very long contexts may be truncated

### Risks

1. **Over-Reliance:** Risk of trusting AI outputs without proper validation
2. **Data Leakage:** Risk of sending sensitive data to inappropriate models
3. **Incorrect Decisions:** Risk of making security decisions based on incorrect AI outputs
4. **Compliance Issues:** Risk of non-compliance if AI outputs don't meet requirements
5. **Reputation:** Risk to organizational reputation if incorrect AI outputs are published

### Mitigation Strategies

1. **Mandatory Human Review:** Always require expert review
2. **Source Verification:** Cross-reference with authoritative sources
3. **Model Selection:** Choose appropriate models for data classification
4. **Feedback Loops:** Provide feedback to improve accuracy
5. **Training:** Ensure users are properly trained
6. **Monitoring:** Monitor AI usage and outcomes
7. **Documentation:** Document all AI-assisted decisions

---

## Contact and Support

### Point of Contact

For questions, concerns, or support regarding Aegis AI:

**Slack:** Contact the Aegis team on Slack 

**GitHub Issues:** [https://github.com/RedHatProductSecurity/aegis-ai/issues](https://github.com/RedHatProductSecurity/aegis-ai/issues)

### Feedback Mechanism

Submit feedback about AI outputs:

**Via REST API:**
```bash
POST /api/v1/feedback
```

**Feedback should include:**
- Feature name
- CVE ID (if applicable)
- Whether you accepted or rejected the suggestion
- Actual result received
- Expected result (if different)
- Comments explaining your decision

### Reporting Issues

Report issues with:

- Incorrect AI outputs
- Missing or incomplete information
- Tool failures or errors
- Security concerns
- Suggestions for improvements

---

## Summary

### Key Points

1. **Aegis uses AI:** All suggestions are AI-generated and require human review
2. **Training Required:** Users must understand limitations and best practices
3. **Human Review Mandatory:** Never use AI outputs without expert validation
4. **Appropriate Use:** Use AI as an assistant, not a replacement for expertise
5. **Data Classification:** Match model selection to data sensitivity
6. **Feedback Welcome:** Your feedback helps improve the tool

### Remember

- ✅ AI assists but doesn't replace human expertise
- ✅ Always review and validate AI outputs
- ✅ Use appropriate models for your data classification
- ✅ Document your review decisions
- ✅ Provide feedback to improve the tool
- ❌ Never use AI outputs without human review
- ❌ Never send classified data to public cloud models
- ❌ Never make final decisions based solely on AI outputs

---

## Additional Resources

- [User Guide](USER_GUIDE.md) - Comprehensive user documentation
- [Configuration Reference](env-vars.md) - Environment variables
- [OpenAPI Specification](openapi.yml) - API documentation

---

**Version:** See [CHANGELOG.md](CHANGELOG.md)

**For questions or concerns about AI usage in Aegis, contact the Aegis team on Slack** 
