CalvinBackup/agentic_security
1
0
Fork 0
mirror of https://github.com/msoedov/agentic_security.git synced 2026-06-23 21:59:57 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs + pre commit):

Browse Source
This commit is contained in:
Alexander Myasoedov
2025-02-11 15:34:12 +02:00
parent 152c87611f
commit 851a0f03a8
6 changed files with 315 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/pre-commit.yml
+21
View File
@@ -0,0 +1,21 @@
name: Pre-Commit Checks
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
pre-commit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.x'
- name: Install pre-commit
run: pip install pre-commit
- name: Run pre-commit
run: pre-commit run --all-files
.github/workflows/test.yml
-4
View File
@@ -29,10 +29,6 @@ jobs:
cache: "poetry"
- name: Install dependencies
run: poetry install
- name: Install pre-commit
run: pip install pre-commit
- name: Run pre-commit
run: pre-commit run --all-files
- name: Run unit tests
run: |
poetry run pytest .
docs/abstractions.md
+55
View File
@@ -0,0 +1,55 @@
# Abstractions in Agentic Security
This document outlines the key abstractions used in the Agentic Security project, providing insights into the classes, interfaces, and design patterns that form the backbone of the system.
## Key Abstractions
### AgentSpecification
- **Purpose**: Defines the specification for a language model or agent, including its name, version, description, capabilities, and configuration settings.
- **Usage**: Used to initialize and configure the `OperatorToolBox` and other components that interact with language models.
### OperatorToolBox
- **Purpose**: Serves as the main class for managing dataset operations, including validation, execution, and result retrieval.
- **Methods**:
- `get_spec()`: Returns the agent specification.
- `get_datasets()`: Retrieves the datasets for operations.
- `validate()`: Validates the toolbox setup.
- `run_operation(operation: str)`: Executes a specified operation.
### DatasetManagerAgent
- **Purpose**: Provides tools for managing and executing operations on datasets through an agent-based approach.
- **Tools**:
- `validate_toolbox`: Validates the `OperatorToolBox`.
- `execute_operation`: Executes operations on datasets.
- `retrieve_results`: Retrieves operation results.
- `retrieve_failures`: Retrieves any failures encountered.
### ProbeDataset
- **Purpose**: Represents a dataset used in security scans, including metadata, prompts, and associated costs.
- **Methods**:
- `metadata_summary()`: Provides a summary of the dataset's metadata.
### Refusal Classifier
- **Purpose**: Analyzes responses from language models to detect potential security vulnerabilities.
- **Design**: Utilizes predefined rules and machine learning models for classification.
## Design Patterns
### Modular Architecture
- **Description**: The system is designed with a modular architecture, allowing for easy integration of new components and features.
- **Benefits**: Enhances flexibility, extensibility, and scalability.
### Agent-Based Design
- **Description**: Utilizes an agent-based approach for managing and executing operations on datasets.
- **Benefits**: Provides a structured framework for interacting with language models and datasets.
## Conclusion
The abstractions in Agentic Security are designed to provide a flexible and extensible framework for managing and executing security scans on language models. This document highlights the key classes, interfaces, and design patterns that contribute to the system's architecture and functionality.
docs/design.md
+51
View File
@@ -0,0 +1,51 @@
# Design Document
This document provides an overview of the design and architecture of the Agentic Security project. It outlines the key components, their interactions, and the design principles guiding the development of the system.
## Overview
Agentic Security is an open-source LLM vulnerability scanner designed to identify and mitigate potential security threats in language models. It integrates various modules and datasets to perform comprehensive security scans.
## Architecture
The system is built around a modular architecture, allowing for flexibility and extensibility. The core components include:
- **Agentic Security Core**: The main application responsible for orchestrating the security scans and managing interactions with external modules.
- **Probe Actor**: Handles the execution of fuzzing and attack techniques on language models.
- **Probe Data**: Manages datasets used for testing and validation, including loading and processing data.
- **Refusal Classifier**: Analyzes responses from language models to identify potential security issues.
## Key Components
### Agentic Security Core
The core application is responsible for initializing the system, managing configurations, and coordinating the execution of security scans. It provides a command-line interface for users to interact with the system.
### Probe Actor
The Probe Actor module implements various fuzzing and attack techniques. It is designed to test the robustness of language models by simulating different attack scenarios.
### Probe Data
The Probe Data module manages datasets used in security scans. It supports loading data from local files and external sources, providing a flexible framework for testing different scenarios.
### Refusal Classifier
The Refusal Classifier analyzes responses from language models to detect potential security vulnerabilities. It uses predefined rules and machine learning models to classify responses.
## Design Principles
- **Modularity**: The system is designed to be modular, allowing for easy integration of new components and features.
- **Extensibility**: New modules and datasets can be added to the system without significant changes to the core architecture.
- **Scalability**: The system is built to handle large datasets and complex security scans efficiently.
## Interaction Flow
1. **Initialization**: The system is initialized with the necessary configurations and datasets.
2. **Execution**: The Probe Actor executes security scans on the language models using the datasets provided by the Probe Data module.
3. **Analysis**: The Refusal Classifier analyzes the responses to identify potential security issues.
4. **Reporting**: Results are compiled and presented to the user, highlighting any vulnerabilities detected.
## Conclusion
The design of Agentic Security emphasizes flexibility, extensibility, and scalability, providing a robust framework for identifying and mitigating security threats in language models. This document serves as a guide to understanding the system's architecture and key components.
docs/operator.md
+123
View File
@@ -0,0 +1,123 @@
# Operator Module
The `operator.py` module provides tools for managing and operating on datasets using an agent-based approach. It is designed to facilitate the execution of operations on datasets through a structured and validated process.
## Classes
### AgentSpecification
Defines the specification for an LLM/agent:
- `name`: Name of the LLM/agent
- `version`: Version of the LLM/agent
- `description`: Description of the LLM/agent
- `capabilities`: List of capabilities
- `configuration`: Configuration settings
### OperatorToolBox
Main class for dataset operations:
- `__init__(spec: AgentSpecification, datasets: list[dict[str, Any]])`: Initialize with agent spec and datasets. This sets up the toolbox with the necessary specifications and datasets for operation.
- `get_spec()`: Get the agent specification. Returns the `AgentSpecification` object associated with the toolbox.
- `get_datasets()`: Get the datasets. Returns a list of datasets that the toolbox operates on.
- `validate()`: Validate the toolbox. Checks if the toolbox is correctly set up with valid specifications and datasets.
- `stop()`: Stop the toolbox. Halts any ongoing operations within the toolbox.
- `run()`: Run the toolbox. Initiates the execution of operations as defined in the toolbox.
- `get_results()`: Get operation results. Retrieves the results of operations performed by the toolbox.
- `get_failures()`: Get failures. Provides a list of any failures encountered during operations.
- `run_operation(operation: str)`: Run a specific operation. Executes a given operation on the datasets, returning the result or failure message.
## Agent Tools
The `dataset_manager_agent` provides these tools:
### validate_toolbox
Validates the OperatorToolBox:
```python
@dataset_manager_agent.tool
async def validate_toolbox(ctx: RunContext[OperatorToolBox]) -> str
```
### execute_operation
Executes an operation on a dataset:
```python
@dataset_manager_agent.tool
async def execute_operation(ctx: RunContext[OperatorToolBox], operation: str) -> str
```
### retrieve_results
Retrieves operation results:
```python
@dataset_manager_agent.tool
async def retrieve_results(ctx: RunContext[OperatorToolBox]) -> str
```
### retrieve_failures
Retrieves failures:
```python
@dataset_manager_agent.tool
async def retrieve_failures(ctx: RunContext[OperatorToolBox]) -> str
```
## Usage Examples
### Initializing the OperatorToolBox
To initialize the `OperatorToolBox`, you need to provide an `AgentSpecification` and a list of datasets:
```python
spec = AgentSpecification(
name="GPT-4",
version="4.0",
description="A powerful language model",
capabilities=["text-generation", "question-answering"],
configuration={"max_tokens": 100},
)
datasets = [{"name": "dataset1"}, {"name": "dataset2"}]
toolbox = OperatorToolBox(spec=spec, datasets=datasets)
```
### Synchronous Usage
```python
def run_dataset_manager_agent_sync():
prompts = [
"Validate the toolbox.",
"Execute operation on 'dataset2'.",
"Retrieve the results.",
"Retrieve any failures."
]
for prompt in prompts:
result = dataset_manager_agent.run_sync(prompt, deps=toolbox)
print(f"Response: {result.data}")
```
### Asynchronous Usage
```python
async def run_dataset_manager_agent_async():
prompts = [
"Validate the toolbox.",
"Execute operation on 'dataset2'.",
"Retrieve the results.",
"Retrieve any failures."
]
for prompt in prompts:
result = await dataset_manager_agent.run(prompt, deps=toolbox)
print(f"Response: {result.data}")
```
These updates provide a more detailed and comprehensive understanding of the `operator.py` module, its classes, and its usage.
docs/quickstart.md
+65
View File
@@ -0,0 +1,65 @@
# Quickstart Guide
Welcome to the Quickstart Guide for Agentic Security. This guide will help you set up and start using the project quickly.
## Installation
To get started with Agentic Security, install the package using pip:
```shell
pip install agentic_security
```
## Initial Setup
After installation, you can start the application using the following command:
```shell
agentic_security
```
This will initialize the server and prepare it for use.
## Basic Usage
To run the main application, use:
```shell
python -m agentic_security
```
You can also view help options with:
```shell
agentic_security --help
```
## Running as a CI Check
Initialize the configuration for CI checks:
```shell
agentic_security init
```
This will generate a default configuration file named `agesec.toml`.
## Additional Commands
- List available modules:
```shell
agentic_security ls
```
- Run a security scan:
```shell
agentic_security ci
```
## Further Information
For more detailed information, refer to the [Documentation](index.md) or the [API Reference](api_reference.md).
This quickstart guide should help you get up and running with Agentic Security efficiently.