README.md

metadata

license: mit
title: Phishing-env
sdk: docker
emoji: 🌍
colorFrom: blue
colorTo: purple
short_description: A smol enviornment to distuinguish spam and normal mails.

PhishGuard-Env

An OpenEnv-compliant SOC analyst simulation environment for benchmarking LLM-based email triage agents.

Overview

PhishGuard-Env presents an agent with phishing, malware, BEC, spam, and safe emails. The agent must classify each one using a four-action triage system. Rewards are graded continuously in (0.0, 1.0) — never 0, never 1 — and a health system penalises critical mistakes.

Difficulty Levels

Level	Scenarios	Tasks
easy	lv1–lv3	3
medium	lv4–lv7	4
hard	lv8–lv10	3

Action Space

Action	When to use
MARK_SAFE	Confirmed legitimate email — deliver to inbox
MOVE_TO_SPAM	Bulk / unsolicited mail, no active threat
QUARANTINE	Suspicious but unconfirmed — hold for review
BLOCK_DOMAIN	Confirmed phishing / BEC / malware source

Quickstart

1. Clone and install

git clone https://github.com/your-username/phishguard-env
cd phishguard-env
pip install -r requirements.txt

2. Configure credentials

cp .env.example .env
# Edit .env and set HF_TOKEN or OPENAI_API_KEY

3. Start the environment server

python env.py
# Server starts on http://localhost:7860

4. Run the inference agent

# All three levels
python inference.py

# Single level
python inference.py --level hard

# Custom output path
python inference.py --output my_run.json

5. Run tests

pytest test_grader.py -v

Docker

docker build -t phishguard-env .
docker run -p 7860:7860 -e HF_TOKEN=hf_... phishguard-env

API Reference

POST /reset

Start a new episode at the chosen difficulty level. The request body is optional — if omitted, defaults to "easy".

{ "level": "easy" }

POST /step

Submit one triage action.

{ "action": "BLOCK_DOMAIN", "reasoning": "Domain registered 3 days ago with SPF fail." }

GET /state

Read-only snapshot of current environment state.

GET /health

Liveness probe for HF Spaces / load-balancers.

Environment Variables

Variable	Default	Description
HF_TOKEN	—	Hugging Face API key
OPENAI_API_KEY	—	OpenAI-compatible API key
API_BASE_URL	https://router.huggingface.co/v1	LLM API base URL
MODEL_NAME	Qwen/Qwen2.5-72B-Instruct	Model to use for inference
ENV_BASE_URL	http://localhost:7860	Environment server URL