Amass API is a Flask-based web application designed to interact with OWASP Amass, enabling domain enumeration via a simple REST API. This API can be used by cybersecurity professionals to automate the discovery of subdomains during penetration testing, saving time and effort compared to manual methods. It provides options for recursive enumeration and brute-forcing subdomains, with results saved in a structured format.
- Async Task Processing: Queue-based system that processes one task at a time
- SQLite Database: Persistent storage for all tasks and results
- Task Management: Create, monitor, and retrieve task status and results
- Queue Monitoring: View current queue status and active tasks
- Flexible Execution: Support for both synchronous and asynchronous task execution
- Domain URL Support: Extract domains from full URLs or use direct domain input
- Docker Persistence: SQLite database and results persist across container restarts
- RESTful API: Clean REST endpoints for all operations
- Docker
- Docker Compose
You can use the prebuilt Docker image from Docker Hub to quickly deploy the API:
docker pull enrikenur/amass-apiFollow these steps to set up the application:
- Clone the repository:
git clone https://github.com/w95/amass-api cd amass-api - Build and start the application using Docker Compose:
docker-compose up --build
- Once running, access the API at
http://localhost:5000.
Check if the API is running.
Response:
{
"status": "ok"
}Create a new enumeration task (synchronous or asynchronous).
Request Body (JSON):
| Parameter | Type | Required | Description |
|---|---|---|---|
domain |
String | Yes | The target domain or URL for enumeration. |
brute |
Boolean | No | Enable brute-forcing of subdomains. Default: false. |
min_for_recursive |
Integer | No | Minimum number of findings to trigger recursion. Default: 2. |
async |
Boolean | No | Run task asynchronously. Default: false. |
Example Requests:
Synchronous task:
curl -X POST http://localhost:5000/task \
-H "Content-Type: application/json" \
-d '{"domain": "example.com", "brute": true}'Asynchronous task:
curl -X POST http://localhost:5000/task \
-H "Content-Type: application/json" \
-d '{"domain": "example.com", "brute": true, "async": true}'Response:
- Sync Success:
{ "status": "success", "message": "Amass enumeration completed.", "task_id": "uuid-task-id", "domain": "example.com", "output": ["subdomain1.example.com", "subdomain2.example.com"] } - Async Success:
{ "status": "success", "message": "Task queued successfully", "task_id": "uuid-task-id", "domain": "example.com", "async": true }
Get the status and results of a specific task.
Example:
curl http://localhost:5000/task/uuid-task-idResponse:
{
"task_id": "uuid-task-id",
"domain": "example.com",
"status": "completed",
"created_at": "2025-06-12T02:30:00",
"started_at": "2025-06-12T02:30:05",
"completed_at": "2025-06-12T02:31:20",
"brute": true,
"min_for_recursive": 2,
"async": true,
"output": ["subdomain1.example.com", "subdomain2.example.com"]
}Task Status Values:
pending- Task is queuedrunning- Task is currently executingcompleted- Task finished successfullyfailed- Task failed (checkerror_message)
View the current queue status.
Example:
curl http://localhost:5000/queueResponse:
{
"status": "success",
"queue_size": 2,
"current_task": "uuid-of-running-task",
"worker_active": true
}List all tasks with their basic information.
Example:
curl http://localhost:5000/tasksResponse:
{
"status": "success",
"total": 5,
"tasks": [
{
"id": "uuid-task-1",
"domain": "example.com",
"status": "completed",
"created_at": "2025-06-12T02:30:00",
"brute": true,
"async": true
}
]
}The API uses SQLite for persistent data storage:
- Database:
./data/amass_tasks.db(persisted via Docker volume) - Results:
./results/directory (persisted via Docker volume) - Task History: All tasks, their parameters, status, and results are stored
- Queue State: Tasks survive container restarts
For local development without Docker:
-
Install dependencies:
pip3.10 install -r requirements.txt
-
Create necessary directories:
mkdir -p data results
-
Run the application:
python3.10 app.py
The API will be available at http://localhost:5000.
The SQLite database contains a tasks table with the following structure:
CREATE TABLE tasks (
id TEXT PRIMARY KEY, -- UUID task identifier
domain TEXT NOT NULL, -- Target domain
brute BOOLEAN NOT NULL DEFAULT FALSE, -- Brute force enabled
min_for_recursive INTEGER DEFAULT 2, -- Minimum for recursion
async BOOLEAN NOT NULL DEFAULT FALSE, -- Async execution
status TEXT NOT NULL DEFAULT 'pending', -- Task status
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
started_at TIMESTAMP NULL,
completed_at TIMESTAMP NULL,
result TEXT NULL, -- Amass output
error_message TEXT NULL, -- Error details if failed
output_file TEXT NULL -- Path to output file
);-
Check API health:
curl http://localhost:5000/
-
Queue an async task:
curl -X POST http://localhost:5000/task \ -H "Content-Type: application/json" \ -d '{"domain": "example.com", "brute": true, "async": true}'
-
Check queue status:
curl http://localhost:5000/queue
-
Monitor task progress:
curl http://localhost:5000/task/your-task-id
-
List all tasks:
curl http://localhost:5000/tasks
The API provides detailed error messages for various scenarios:
- 400 Bad Request: Missing required parameters
- 404 Not Found: Task ID not found
- 500 Internal Server Error: Amass execution failed or other server errors
All error responses follow this format:
{
"status": "error",
"message": "Error description"
}This project is licensed under the MIT License. See LICENSE for more details.
- OWASP Amass for providing the enumeration tool.
Contributions are welcome! Please fork the repository and submit a pull request with your changes.