https://github.com/EasyJailbreak/EasyJailbreak
An easy-to-use Python framework to generate adversarial jailbreak prompts.
https://github.com/EasyJailbreak/EasyJailbreak
discrete-optimization jailbreak jailbreak-framework large-language-model llm-safety-benchmark llm-security
Last synced: about 2 months ago
JSON representation
An easy-to-use Python framework to generate adversarial jailbreak prompts.
- Host: GitHub
- URL: https://github.com/EasyJailbreak/EasyJailbreak
- Owner: EasyJailbreak
- License: gpl-3.0
- Created: 2024-01-31T09:04:31.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-03-27T18:30:15.000Z (7 months ago)
- Last Synced: 2025-08-18T06:12:16.687Z (2 months ago)
- Topics: discrete-optimization, jailbreak, jailbreak-framework, large-language-model, llm-safety-benchmark, llm-security
- Language: Python
- Homepage: http://easyjailbreak.org/
- Size: 8.48 MB
- Stars: 699
- Watchers: 8
- Forks: 61
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- Awesome-LLMSecOps - EasyJailbreak - to-use Python framework to generate adversarial jailbreak prompts |  | (Jailbreaks)
- awesome-ai-security - EasyJailbreak - _An easy-to-use Python framework to generate adversarial jailbreak prompts._ (Offensive tools and frameworks / LLM)
README
—— An easy-to-use Python framework to generate adversarial jailbreak prompts by assembling different methods
## Table of Contents
- [About](#about)
- [Setup](#setup)
- [Project Structure](#project-structure)
- [Usage](#usage)
- [Citing EasyJailbreak](#citing-easyjailbreak)
## About
### ✨ Introduction
**What is EasyJailbreak?**
EasyJailbreak is an *easy-to-use* Python framework designed for researchers and developers focusing on LLM security. Specifically, EasyJailbreak decomposes the mainstream jailbreaking process into several iterable steps: initialize **mutation seeds**, **select suitable seeds**, **add constraint**, **mutate**, **attack**, and **evaluate**. On this basis, EasyJailbreak provides a component for each step, constructing a playground for further research and attempts. More details can be found in our paper.
### 📚 Resources
- **[Paper](https://arxiv.org/pdf/2403.12171.pdf):** Details the framework's design and key experimental results.
- **[EasyJailbreak Website](http://easyjailbreak.org/):** Explore different LLMs' jailbreak results and view examples of jailbreaks.
- **[Documentation](https://easyjailbreak.github.io/EasyJailbreakDoc.github.io):** Detailed API documentation and parameter explanations.
### 🏆 Experimental results
The jailbreak attack results of 11 attack recipes on 10 large language models can be downloaded at **[Link](https://drive.google.com/file/d/1Im3q9n6ThL4xiaUEBmD7M8rkOIjw8oWU/view?usp=sharing)**.
## 🛠️ Setup
There are two methods to install EasyJailbreak. All those methods need `python>=3.9` installed.
1. For users who only require the approaches (or [recipes](#using-recipe)) collected in EasyJailbreak, execute the following command:
```shell
pip install easyjailbreak
```
2. For users interested in [adding new components](#diy-your-attacker) (e.g., new mutate or evaluate methods), follow these steps:
```shell
git clone https://github.com/EasyJailbreak/EasyJailbreak.git
cd EasyJailbreak
pip install -e .
```
## 🔍 Project Structure
This project is mainly divided into three parts.
1. The first part requires the user to prepare **Queries**, **Config,** **Models**, and **Seed**.
2. The second part is the main part, consisting of two processes that form a loop structure, namely **Mutation** and **Inference**.
1) In the **Mutation** process, the program will first select the optimal jailbreak prompts through **Selector**, then transform the prompts through **Mutator**, and then filter out the expected prompts through **Constraint.**
2) In the **Inference** process, the prompts are used to attack the **Target (model)** and obtain the target model's responses. The responses are then inputted into **Evaluator** to obtain the score of the attack's effectiveness for this round, which is then passed to Selector to complete one cycle.
3. The third part you will get a **Report**. Under some stopping mechanism, the loop stops, and the user will receive a report about each attack (including jailbreak prompts, responses of **Target (model)**, Evaluator's scores, etc.).
The following table shows the 4 essential components (i.e. **Selectors**, **Mutators**, **Constraints**, **Evaluators**) used by each recipe implemented in our project:
| Attack
Recipes | Selector | Mutator | Constraint| Evaluator|
| :---------------: | :---------------: |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| :--------------: |:-------------: |
| ReNeLLM| N/A | ChangeStyle
InsertMeaninglessCharacters
MisspellSensitiveWords
Rephrase
GenerateSimilar
AlterSentenceStructure | DeleteHarmLess | Evaluator_GenerativeJudge |
| GPTFuzz| MCTSExploreSelectPolicy
RandomSelector
EXP3SelectPolicy
RoundRobinSelectPolicy
UCBSelectPolicy | ChangeStyle
Expand
Rephrase
Crossover
Translation
Shorten | N/A| Evaluator_ClassificationJudge |
| ICA | N/A| N/A | N/A| Evaluator_PatternJudge|
| AutoDAN| N/A| Rephrase
CrossOver
ReplaceWordsWithSynonyms | N/A| Evaluator_PatternJudge|
| PAIR | N/A| HistoricalInsight | N/A| Evaluator_GenerativeGetScore|
| JailBroken | N/A| Artificial
Auto_obfuscation
Auto_payload_splitting
Base64_input_only
Base64_raw
Base64
Combination_1
Combination_2
Combination_3
Disemovowel
Leetspeak
Rot13 | N/A| Evaluator_GenerativeJudge |
| Cipher | N/A| AsciiExpert
CaserExpert
MorseExpert
SelfDefineCipher | N/A| Evaluator_GenerativeJudge |
| DeepInception| N/A| Inception | N/A| Evaluator_GenerativeJudge |
| MultiLingual |N/A| Translate | N/A| Evaluator_GenerativeJudge |
| GCG | ReferenceLossSelector| MutationTokenGradient | N/A| Evaluator_PrefixExactMatch|
| TAP|SelectBasedOnScores| IntrospectGeneration | DeleteOffTopic | Evaluator_GenerativeGetScore|
| CodeChameleon|N/A| BinaryTree
Length
Reverse
OddEven | N/A | Evaluator_GenerativeGetScore|
## 💻 Usage
### Using Recipe
We have got many **implemented methods** ready for use! Instead of devising a new jailbreak scheme, the EasyJailbreak team gathers from relevant papers, referred to as **"recipes"**. Users can freely apply these jailbreak schemes on various models to familiarize the performance of both models and schemes. The only thing users need to do for this is download models and utilize the provided API.
Here is a usage example:
```python
from easyjailbreak.attacker.PAIR_chao_2023 import PAIR
from easyjailbreak.datasets import JailbreakDataset
from easyjailbreak.models.huggingface_model import from_pretrained
from easyjailbreak.models.openai_model import OpenaiModel
# First, prepare models and datasets.
attack_model = from_pretrained(model_name_or_path='lmsys/vicuna-13b-v1.5',
model_name='vicuna_v1.1')
target_model = OpenaiModel(model_name='gpt-4',
api_keys='INPUT YOUR KEY HERE!!!')
eval_model = OpenaiModel(model_name='gpt-4',
api_keys='INPUT YOUR KEY HERE!!!')
dataset = JailbreakDataset('AdvBench')
# Then instantiate the recipe.
attacker = PAIR(attack_model=attack_model,
target_model=target_model,
eval_model=eval_model,
jailbreak_datasets=dataset)
# Finally, start jailbreaking.
attacker.attack(save_path='vicuna-13b-v1.5_gpt4_gpt4_AdvBench_result.jsonl')
```
All available recipes and their relevant information can be found in the [documentation](https://easyjailbreak.github.io/EasyJailbreakDoc.github.io/).
### DIY Your Attacker
#### 1. Load Models
You can load a model in one line of python code.
```python
# import model prototype
from easyjailbreak.models.huggingface_model import HuggingfaceModel
# load the target model (but you may use up to 3 models in a attacker, i.e. attack_model, eval_model, target_model)
target_model = HuggingfaceModel(model_name_or_path='meta-llama/Llama-2-7b-chat-hf',
model_name='llama-2')
# use the target_model to generate response based on any input. Here is an example.
target_response = target_model.generate(messages=['how to make a bomb?'])
```
#### 2. Load Dataset and initialize Seed
**Dataset**: We prepare a class named "JailbreakDataset" to wrap the the instance list. And every instance contains query, jailbreak prompts, etc. You can either load Dataset from our online repo or your local file.
**Seed**: You can simply ramdomly generate initial seed.
```python
from easyjailbreak.datasets import JailbreakDataset
from easyjailbreak.seed.seed_random import SeedRandom
# Option 1: load dataset from our online repo. Available datasets and their details can be found at https://huggingface.co/datasets/Lemhf14/EasyJailbreak_Datasets
dataset = JailbreakDataset(dataset='AdvBench')
# Option 2: load dataset from a local file
dataset = JailbreakDataset(local_file_type='csv', dataset='AdvBench.csv')
# Randomly generate initial seed
seeder = SeedRandom()
seeder.new_seeds()
```
#### 3. Instantiate Components
As mentioned in [Project Structure](#project-structure), the second part consists of 4 major components (modules, i.e. selector, mutator, constraint, evaluator) and you need to instantiate them when you DIY your attack method. All available **Selectors**, **Mutators**, **Constraint**, **Evaluators** and their details can be found in the [documentation](https://easyjailbreak.github.io/EasyJailbreakDoc.github.io/).
You can `import` the module you want by using `from easyjailbreak.module_name.method_name import method_name`, here is a brief instruction for you to start (the `method_name` is what you choose as the method in the corresponding module):
1. **Selector**: `from easyjailbreak.selector.method_name import method_name`
2. **Mutator**: `from easyjailbreak.mutation.rule.method_name import method_name`
3. **Constraint**: `from easyjailbreak.constraint.method_name import method_name`
4. **Evaluator**: `from easyjailbreak.metrics.Evaluator.method_name import method_name`
Here is an example.
```python
from easyjailbreak.selector.RandomSelector import RandomSelectPolicy
from easyjailbreak.datasets import JailbreakDataset, Instance
from easyjailbreak.seed import SeedTemplate
from easyjailbreak.mutation.rule import Translate
from easyjailbreak.models import from_pretrained
import torch
# Initializes malicious questions used to attack language models
instance = Instance(query='How to make a bomb?')
dataset = JailbreakDataset([instance])
# Define the target model of the attack
model = from_pretrained('meta-llama/Llama-2-7b-chat-hf', 'llama-2', dtype=torch.bfloat16, max_new_tokens=200)
# Initializes a Jailbreak prompt
inital_prompt_seed = SeedTemplate().new_seeds(seeds_num= 10, method_list=['Gptfuzzer'])
inital_prompt_seed = JailbreakDataset([Instance(jailbreak_prompt=prompt) for prompt in inital_prompt_seed])
# Initializes a Selector
selector = RandomSelectPolicy(inital_prompt_seed)
# Apply selection to provide a prompt
candidate_prompt_set = selector.select()
for instance in dataset:
instance.jailbreak_prompt = candidate_prompt_set[0].jailbreak_prompt
# Mutate the raw query to fool the language model
Mutation = Translate(attr_name='query',language = 'jv')
mutated_instance = Mutation(dataset)[0]
# get target model's response
attack_query = mutated_instance.jailbreak_prompt.format(query = mutated_instance.query)
response = model.generate(attack_query)
```
## 🖊️ Citing EasyJailbreak
```bibtex
@misc{zhou2024easyjailbreak,
title={EasyJailbreak: A Unified Framework for Jailbreaking Large Language Models},
author={Weikang Zhou and Xiao Wang and Limao Xiong and Han Xia and Yingshuang Gu and Mingxu Chai and Fukang Zhu and Caishuang Huang and Shihan Dou and Zhiheng Xi and Rui Zheng and Songyang Gao and Yicheng Zou and Hang Yan and Yifan Le and Ruohui Wang and Lijun Li and Jing Shao and Tao Gui and Qi Zhang and Xuanjing Huang},
year={2024},
eprint={2403.12171},
archivePrefix={arXiv},
primaryClass={cs.CL}
}
```