PurpleAI

📋 Table of contents

• PurpleAI
  • Project description
    • Technologies
  • Prerequisites
  • Getting started
  • Usage Docker
    • Running the Vulnerablea app only
    • Running the Vulnerable app and Defender agent
    • View logs
    • Stop the containers
    • 📖 Generate Documentation Site
  • Testing
  • Team
    • License

Project description

PurpleAI is a student project at Cogito NTNU where we build AI agents that attack and defend. One agent acts as a hacker and tries to break into a deliberately vulnerable web app using techniques like SQL injection. The other acts as a defender, it sits in front of the app as a reverse proxy, uses an LLM to inspect every incoming request, and blocks anything that looks like an attack before it reaches the server. We started with SQL injection on a web app and plan to add more attack types and targets later. Red team + blue team = purple. 💜

Technologies

• LangChain Agents: Autonomous agents with specialized tools for attack and defend mechanism.
• Large Language Models: Different models fron IDUN NTNU for natural language understanding and reasoning.

Prerequisites

• Git: Ensure that git is installed on your machine. Download Git
• Python 3.12: Required for the backend. Download Python
• UV: Used for managing Python environments. Install UV
• Docker & Docker Compose: Required for running the ParadeDB database. Download Docker
• Node.js (v18+): Required for the frontend. Download Node.js
• OpenAI API Key: Required for GPT-4 access. Get API Key

Getting started

1. Clone the repository:

   git clone https://github.com/CogitoNTNU/purpleAI.git
   cd purpleAI

2. Install dependencies:

   uv sync

3. Configure environment variables: This project uses environment variables for configuration. Edit the environment file (.env) to create your own:

    IDUNN_BASE_URL="https://llm.hpc.ntnu.no/v1"
    IDUNN_API_KEY="your-api-key"

Usage Docker

Running the Vulnerablea app only

cd src/defender
docker compose -f docker-compose.app.yml up --build -d

The app will be available at http://localhost:8080. But, if you are using the blueteam computer exchange localhost with the IP-address.

Running the Vulnerable app and Defender agent

cd src/defender
docker compose -f docker-compose.full.yml up --build -d

View logs

docker logs vulnerable-app
docker logs defender 

Stop the containers

docker compose -f docker-compose.app.yml down
docker compose -f docker-compose.full.yml down

📖 Generate Documentation Site

To build and preview the documentation site locally:

uv run mkdocs build
uv run mkdocs serve

This will build the documentation and start a local server at http://127.0.0.1:8000/ where you can browse the docs and API reference. Get the documentation according to the lastes commit on main by viewing the gh-pages branch on GitHub: https://cogitontnu.github.io/PROJECT-TEMPLATE/.

Testing

To run the test suite, run the following command from the root directory of the project:

uv run pytest --doctest-modules --cov=src --cov-report=html

Team

This project was built by the PurpleAI team at Cogito NTNU. Thank you to everyone who contributed their hard work and dedication to making this project possible. It's been a great experience working together on this challenge.

Frederik Lunde

Elisa Gunnarshaug

Adele Thorberg

Vegard Aa Albretsen

Ingunn Tonetta Erdal

Odin Vankan

Daniel Hauksson

License

---

Distributed under the MIT License. See LICENSE for more information.