Skip to main content

​
Overview

Tasks represent high-level objectives within a penetration testing flow. Each task can be decomposed into subtasks for granular execution tracking.

​
Task Type

type Task {
  id: ID!
  title: String!
  status: StatusType!
  input: String!
  result: String!
  flowId: ID!
  subtasks: [Subtask!]
  createdAt: Time!
  updatedAt: Time!
}

​
Fields

​
id
ID
required
Unique identifier for the task
​
title
String
required
Task title generated by the AI agent
​
status
StatusType
required
Current status: created, running, waiting, finished, failed
​
input
String
required
Original task description or objective
​
result
String
required
Task execution results, findings, or error messages
​
flowId
ID
required
ID of the parent flow
​
subtasks
[Subtask!]
List of subtasks for this task

​
Subtask Type

type Subtask {
  id: ID!
  status: StatusType!
  title: String!
  description: String!
  result: String!
  taskId: ID!
  createdAt: Time!
  updatedAt: Time!
}
​
description
String
required
Detailed description of what the subtask should accomplish
​
taskId
ID
required
ID of the parent task

​
Queries

​
List Tasks for Flow

Retrieve all tasks associated with a flow. 
query GetTasks($flowId: ID!) {
  tasks(flowId: $flowId) {
    id
    title
    status
    input
    result
    subtasks {
      id
      status
      title
      description
      result
    }
    createdAt
    updatedAt
  }
}
Variables: 
{
  "flowId": "1"
}
Response: 
{
  "data": {
    "tasks": [
      {
        "id": "task-001",
        "title": "Reconnaissance and Information Gathering",
        "status": "finished",
        "input": "Gather information about the target web application",
        "result": "Successfully identified target technology stack: Apache 2.4, PHP 7.4, MySQL. Discovered 12 subdomains and mapped site structure.",
        "subtasks": [
          {
            "id": "subtask-001",
            "status": "finished",
            "title": "DNS Enumeration",
            "description": "Perform DNS queries to identify subdomains and mail servers",
            "result": "Found 12 subdomains using multiple DNS enumeration techniques"
          },
          {
            "id": "subtask-002",
            "status": "finished",
            "title": "Technology Detection",
            "description": "Identify web server, frameworks, and technologies in use",
            "result": "Detected: Apache 2.4.41, PHP 7.4.3, jQuery 3.5.1, Bootstrap 4.5"
          }
        ],
        "createdAt": "2024-02-20T10:30:10Z",
        "updatedAt": "2024-02-20T10:35:45Z"
      },
      {
        "id": "task-002",
        "title": "Vulnerability Scanning",
        "status": "running",
        "input": "Scan for common web vulnerabilities",
        "result": "",
        "subtasks": [
          {
            "id": "subtask-003",
            "status": "running",
            "title": "SQL Injection Testing",
            "description": "Test input fields for SQL injection vulnerabilities",
            "result": ""
          }
        ],
        "createdAt": "2024-02-20T10:36:00Z",
        "updatedAt": "2024-02-20T10:36:30Z"
      }
    ]
  }
}

​
Subscriptions

​
Task Created

Subscribe to new task creation within a flow. 
subscription TaskCreated($flowId: ID!) {
  taskCreated(flowId: $flowId) {
    id
    title
    status
    input
    subtasks {
      id
      status
      title
      description
    }
    createdAt
  }
}
Variables: 
{
  "flowId": "1"
}

​
Task Updated

Receive real-time updates when a task’s status or results change. 
subscription TaskUpdated($flowId: ID!) {
  taskUpdated(flowId: $flowId) {
    id
    status
    result
    subtasks {
      id
      status
      result
    }
    updatedAt
  }
}

​
Execution Flow

Tasks follow a hierarchical execution pattern:
  1. Task Creation: Primary agent creates high-level tasks
  2. Subtask Generation: Generator agent breaks down tasks into subtasks
  3. Subtask Execution: Specialized agents (pentester, coder, searcher) execute subtasks
  4. Result Aggregation: Results are collected and summarized
  5. Task Completion: Task status updates to finished or failed

​
Example: Complete Task Lifecycle

# Initial query to get flow tasks
query {
  tasks(flowId: "1") {
    id
    title
    status
  }
}

# Subscribe to task updates
subscription {
  taskUpdated(flowId: "1") {
    id
    status
    result
    subtasks {
      id
      status
      title
      result
    }
    updatedAt
  }
}

​
Agent Types in Task Execution

Different AI agents handle different aspects of task execution:
Breaks down high-level tasks into specific, actionable subtasks
Executes security testing and vulnerability assessments
Writes and executes custom scripts and exploits
Performs web searches and gathers external intelligence
Installs required tools and dependencies
Analyzes results and provides insights

​
Best Practices

Use subscriptions to monitor task progress in real-time rather than polling the API.
Tasks may enter waiting status if they require user input or approval. Monitor the parent flow status to detect this state.

Build docs developers (and LLMs) love

Get started for freeTalk to us