list_scans

Instructions

    List scans in the Intruder account with optional filters.

    Args:
        status: Filter by scan status (in_progress, completed, cancelled, cancelled_no_active_targets,
               cancelled_no_valid_targets, analysing_results)
        scan_type: Filter by scan type (assessment_schedule, new_service, cloudbot_new_target,
                 rapid_remediation, advisory, cloud_security)
    
    The scan_type parameters mean:
        - assessment_schedule: Scans that run on a regular schedule
        - new_service: Scans that are triggered when a new service is exposed on a target
        - cloudbot_new_target: Scans that are triggered when CloudBot discovers a new target in a connected cloud account
        - rapid_remediation: Scans that a user can trigger to test if a specific issue has been remediated
        - advisory: An issue created by the Intruder security team based on their manual work
        - cloud_security: Scans of cloud accounts, checking the configuration of the resources in the cloud account
    

Implementation Reference

• intruder_mcp/server.py:68-89 (handler)

  The MCP tool handler for 'list_scans'. This is the function decorated with @mcp.tool() that registers 'list_scans' as an MCP tool. It accepts optional 'status' and 'scan_type' filters, calls api.list_scans_all() to get all scans from the API, and formats them as a newline-separated list of 'id - scan_type (status)'.

  @mcp.tool()
  async def list_scans(status: Optional[str] = None, scan_type: Optional[str] = None) -> str:
      """
      List scans in the Intruder account with optional filters.
  
      Args:
          status: Filter by scan status (in_progress, completed, cancelled, cancelled_no_active_targets,
                 cancelled_no_valid_targets, analysing_results)
          scan_type: Filter by scan type (assessment_schedule, new_service, cloudbot_new_target,
                   rapid_remediation, advisory, cloud_security)
      
      The scan_type parameters mean:
          - assessment_schedule: Scans that run on a regular schedule
          - new_service: Scans that are triggered when a new service is exposed on a target
          - cloudbot_new_target: Scans that are triggered when CloudBot discovers a new target in a connected cloud account
          - rapid_remediation: Scans that a user can trigger to test if a specific issue has been remediated
          - advisory: An issue created by the Intruder security team based on their manual work
          - cloud_security: Scans of cloud accounts, checking the configuration of the resources in the cloud account
      """
      scans = api.list_scans_all(status=status, scan_type=scan_type)
      formatted = [f"{scan.id} - {scan.scan_type} ({scan.status})" for scan in scans]
      return "\n".join(formatted)

• intruder_mcp/api_client.py:146-156 (helper)

  The 'list_scans_all' method on the API client. This is a pagination helper that calls the underlying 'list_scans' method in a loop (with offset pagination) to yield all ScanList objects. It passes through 'scan_type', 'schedule_period', and 'status' filters.

  def list_scans_all(self, scan_type: Optional[str] = None, schedule_period: Optional[str] = None,
                    status: Optional[str] = None) -> Generator[ScanList, None, None]:
      offset = 0
      while True:
          response = self.list_scans(scan_type=scan_type, schedule_period=schedule_period,
                                   status=status, limit=100, offset=offset)
          for scan in response.results:
              yield scan
          if not response.next:
              break
          offset += len(response.results)

• intruder_mcp/api_client.py:130-144 (helper)

  The 'list_scans' method on the API client. This is the raw API call that sends a GET request to /scans/ with optional query parameters (scan_type, schedule_period, status, limit, offset) and returns a PaginatedScanListList response.

  def list_scans(self, scan_type: Optional[str] = None, schedule_period: Optional[str] = None,
                status: Optional[str] = None, limit: Optional[int] = None,
                offset: Optional[int] = None) -> PaginatedScanListList:
      params = {}
      if scan_type:
          params["scan_type"] = scan_type
      if schedule_period:
          params["schedule_period"] = schedule_period
      if status:
          params["status"] = status
      if limit:
          params["limit"] = limit
      if offset:
          params["offset"] = offset
      return PaginatedScanListList(**self.client.get(f"{self.base_url}/scans/", params=params).json())

• intruder_mcp/enums.py:141-146 (schema)

  The 'ScanList' Pydantic model used as the response schema for list_scans. Contains id, status, created_at, scan_type, and optional schedule_period fields.

  class ScanList(BaseModel):
      id: int
      status: ScanStatusField
      created_at: datetime
      scan_type: ScanTypeEnum
      schedule_period: Optional[SchedulePeriodEnum] = None

• intruder_mcp/enums.py:246-247 (schema)

  The 'PaginatedScanListList' Pydantic model, which is the paginated wrapper containing a list of ScanList results, used as the return type of the API's list_scans method.

  class PaginatedScanListList(PaginatedResponse):
      results: List[ScanList]