{
  "swagger": "2.0",
  "info": {
    "description": "Network scanning solution for information gathering in large IT/OT network environments.",
    "title": "Large-Scale Discovery API",
    "contact": {},
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "1.0"
  },
  "host": "localhost",
  "basePath": "/api/v1",
  "paths": {
    "/scope/targets": {
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns the list of scan targets (inputs) for a specific scope. Requires ownership.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "scopes"
        ],
        "summary": "Get scope targets",
        "parameters": [
          {
            "description": "Scope targets request",
            "name": "request",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handlers.ScopeTargetsRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scope targets retrieved",
            "schema": {
              "$ref": "#/definitions/handlers.ScopeTargetsResponse"
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "503": {
            "description": "Service Unavailable"
          }
        }
      }
    },
    "/scope/update/custom": {
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Creates a new custom scan scope or updates an existing one with scan targets. Supply group_id for creation or scope_id for update. Requires ownership.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "scopes"
        ],
        "summary": "Create or update custom scope",
        "parameters": [
          {
            "description": "Custom scope request",
            "name": "request",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handlers.ScopeCreateUpdateCustomRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scope created or updated",
            "schema": {
              "$ref": "#/definitions/handlers.ScopeCreateUpdateCustomResponse"
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "503": {
            "description": "Service Unavailable"
          }
        }
      }
    },
    "/scopes": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns all scan scopes owned by the current user.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "scopes"
        ],
        "summary": "List scopes",
        "responses": {
          "200": {
            "description": "Scopes retrieved",
            "schema": {
              "$ref": "#/definitions/handlers.ScopesResponse"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "503": {
            "description": "Service Unavailable"
          }
        }
      }
    }
  },
  "definitions": {
    "database.T_scan_agent": {
      "type": "object",
      "properties": {
        "api_version": {
          "type": "string"
        },
        "build_commit": {
          "type": "string"
        },
        "build_timestamp": {
          "type": "string"
        },
        "cpu_cores": {
          "type": "integer"
        },
        "cpu_mhz": {
          "type": "number"
        },
        "cpu_rate": {
          "description": "Usage in %",
          "type": "number"
        },
        "host": {
          "type": "string"
        },
        "id": {
          "description": "Id autoincrement",
          "type": "integer"
        },
        "ip": {
          "type": "string"
        },
        "last_seen": {
          "type": "string"
        },
        "limits": {
          "type": "boolean"
        },
        "memory_bytes": {
          "type": "integer"
        },
        "memory_rate": {
          "description": "Usage in %",
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "platform": {
          "type": "string"
        },
        "platform_family": {
          "type": "string"
        },
        "platform_version": {
          "type": "string"
        },
        "shared": {
          "type": "boolean"
        },
        "tasks": {
          "$ref": "#/definitions/utils.JsonMap"
        },
        "version_nmap": {
          "type": "string"
        },
        "version_npcap": {
          "type": "string"
        },
        "version_python": {
          "type": "string"
        },
        "version_sslyze": {
          "type": "string"
        }
      }
    },
    "database.T_scan_setting": {
      "type": "object",
      "properties": {
        "discovery_exclude_domains": {
          "type": "string"
        },
        "discovery_nmap_args": {
          "type": "string"
        },
        "discovery_nmap_args_ot": {
          "description": "A safer scan executed in OT discovery scans. Field is just required as a JSON field to load default settings from the manager.conf. Not required in the manager database, because it will be copied into the normal nmap args field.",
          "type": "string"
        },
        "discovery_nmap_args_prescan": {
          "description": "A smaller scan executed before the main scan to at least retrieve some scan results, before a potential IDS kicks in",
          "type": "string"
        },
        "discovery_timespans": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/utils.Timespan"
          }
        },
        "http_user_agent": {
          "type": "string"
        },
        "max_instances_banner": {
          "description": "Maximum parallel instances of banner scans per agent.",
          "type": "integer"
        },
        "max_instances_discovery": {
          "description": "Maximum parallel instances of discovery scans per agent.",
          "type": "integer"
        },
        "max_instances_nfs": {
          "description": "Maximum parallel instances of nfs scans per agent.",
          "type": "integer"
        },
        "max_instances_nuclei": {
          "description": "Maximum parallel instances of nuclei scans per agent.",
          "type": "integer"
        },
        "max_instances_smb": {
          "description": "Maximum parallel instances of smb scans per agent.",
          "type": "integer"
        },
        "max_instances_ssh": {
          "description": "Maximum parallel instances of ssh scans per agent.",
          "type": "integer"
        },
        "max_instances_ssl": {
          "description": "Maximum parallel instances of ssl scans per agent.",
          "type": "integer"
        },
        "max_instances_webcrawler": {
          "description": "Maximum parallel instances of webcrawler scans per agent.",
          "type": "integer"
        },
        "max_instances_webenum": {
          "description": "Maximum parallel instances of webenum scans per agent.",
          "type": "integer"
        },
        "network_timeout_seconds": {
          "type": "integer"
        },
        "nfs_accessible_only": {
          "type": "boolean"
        },
        "nfs_depth": {
          "type": "integer"
        },
        "nfs_exclude_extensions": {
          "type": "string"
        },
        "nfs_exclude_file_size_below": {
          "type": "integer"
        },
        "nfs_exclude_folders": {
          "type": "string"
        },
        "nfs_exclude_last_modified_below": {
          "type": "string"
        },
        "nfs_exclude_shares": {
          "type": "string"
        },
        "nfs_scan_timeout_minutes": {
          "type": "integer"
        },
        "nfs_threads": {
          "type": "integer"
        },
        "nuclei_exclude_ids": {
          "type": "string"
        },
        "nuclei_exclude_protocols": {
          "type": "string"
        },
        "nuclei_exclude_severities": {
          "type": "string"
        },
        "nuclei_exclude_tags": {
          "type": "string"
        },
        "nuclei_include_ids": {
          "type": "string"
        },
        "nuclei_include_protocols": {
          "type": "string"
        },
        "nuclei_include_severities": {
          "type": "string"
        },
        "nuclei_include_tags": {
          "type": "string"
        },
        "nuclei_scan_timeout_minutes": {
          "type": "integer"
        },
        "ot": {
          "description": "Enable OT discovery mode (PROFINET DCP, EtherCAT, LLDP, NDP, mDNS) with OT-optimized Nmap timing. Agent auto-detects scan targets based on local configuration.",
          "type": "boolean"
        },
        "sensitive_ports": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "smb_accessible_only": {
          "type": "boolean"
        },
        "smb_depth": {
          "type": "integer"
        },
        "smb_exclude_extensions": {
          "type": "string"
        },
        "smb_exclude_file_size_below": {
          "type": "integer"
        },
        "smb_exclude_folders": {
          "type": "string"
        },
        "smb_exclude_last_modified_below": {
          "type": "string"
        },
        "smb_exclude_shares": {
          "type": "string"
        },
        "smb_forced_shares": {
          "type": "string"
        },
        "smb_scan_timeout_minutes": {
          "type": "integer"
        },
        "smb_threads": {
          "type": "integer"
        },
        "ssh_scan_timeout_minutes": {
          "type": "integer"
        },
        "ssl_scan_timeout_minutes": {
          "type": "integer"
        },
        "webcrawler_always_store_root": {
          "type": "boolean"
        },
        "webcrawler_depth": {
          "type": "integer"
        },
        "webcrawler_follow_query_strings": {
          "type": "boolean"
        },
        "webcrawler_follow_types": {
          "type": "string"
        },
        "webcrawler_max_threads": {
          "type": "integer"
        },
        "webcrawler_scan_timeout_minutes": {
          "type": "integer"
        },
        "webenum_probe_robots": {
          "type": "boolean"
        },
        "webenum_scan_timeout_minutes": {
          "type": "integer"
        }
      }
    },
    "handlers.Connection": {
      "type": "object",
      "properties": {
        "database": {
          "type": "string"
        },
        "host": {
          "type": "string"
        },
        "port": {
          "type": "integer"
        }
      }
    },
    "handlers.Scope": {
      "type": "object",
      "properties": {
        "attributes": {
          "description": "Scope arguments that can be arbitrary to your deployment environment, e.g., describing how to populate, import, refresh, synchronize scan inputs...",
          "allOf": [
            {
              "$ref": "#/definitions/utils.JsonMap"
            }
          ]
        },
        "connection": {
          "description": "The scope's current settings. Can be omitted if user should not see them.",
          "allOf": [
            {
              "$ref": "#/definitions/handlers.Connection"
            }
          ]
        },
        "created": {
          "description": "Timestamp of creation",
          "type": "string"
        },
        "created_by": {
          "description": "User who created this scope",
          "type": "string"
        },
        "cycle": {
          "description": "The current cycle the scan is in. Relevant, if scanning in cycles is enabled",
          "type": "integer"
        },
        "cycle_active": {
          "description": "Percentage of active input scan tasks. Is updated in intervals and not a 100% current.",
          "type": "number"
        },
        "cycle_done": {
          "description": "Percentage of completed input scan tasks. Is updated in intervals and not a 100% current.",
          "type": "number"
        },
        "cycle_failed": {
          "description": "Percentage of failed input scan tasks. Is updated in intervals and not a 100% current.",
          "type": "number"
        },
        "cycle_queue": {
          "description": "Per-module counts of queued scan tasks. Is updated in intervals and not a 100% current.",
          "allOf": [
            {
              "$ref": "#/definitions/utils.JsonMap"
            }
          ]
        },
        "cycle_started": {
          "description": "Timestamp of last cycle start",
          "type": "string"
        },
        "cycles": {
          "description": "Scan in cycles",
          "type": "boolean"
        },
        "cycles_retention": {
          "description": "Amount of previous scan cycles to keep. Older ones will be cleaned up.",
          "type": "integer"
        },
        "enabled": {
          "description": "Whether new target should be fed to scan agents for this scan scope",
          "type": "boolean"
        },
        "group_name": {
          "description": "Expand with additional information useful for the web frontend",
          "type": "string"
        },
        "id": {
          "description": "Id autoincrement",
          "type": "integer"
        },
        "last_sync": {
          "description": "Timestamp when the scan scope targets were set/updated/synchronized the last time",
          "type": "string"
        },
        "name": {
          "description": "Name of the scope selected by the user",
          "type": "string"
        },
        "scan_agents": {
          "description": "The scope's last seen agents. Can be omitted if user should not see them.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/database.T_scan_agent"
          }
        },
        "scan_settings": {
          "description": "The scope's current settings. Can be omitted if user should not see them.",
          "allOf": [
            {
              "$ref": "#/definitions/database.T_scan_setting"
            }
          ]
        },
        "size": {
          "description": "Amount of IPs currently within this scan scope. Needs to be calculated/updated during population of the actual scan scope's t_discovery table.",
          "type": "integer"
        },
        "split_size": {
          "description": "Maximum amount of IPs contained in one scan target after large networks are split",
          "type": "integer"
        },
        "type": {
          "description": "The kind of scope, there might be different ones initialized via different mechanisms. E.g. custom, remote repository,...",
          "type": "string"
        }
      }
    },
    "handlers.ScopeCreateUpdateCustomRequest": {
      "type": "object",
      "properties": {
        "cycles": {
          "description": "Whether to enable cyclic scanning",
          "type": "boolean"
        },
        "cycles_retention": {
          "description": "Amount of scan cycles to keep. -1 to keep all. 0 not allowed.",
          "type": "integer",
          "example": 3
        },
        "group_id": {
          "description": "Set if NEW scope shall be created",
          "type": "integer",
          "example": 1
        },
        "name": {
          "description": "Name of the scan scope",
          "type": "string",
          "example": "My Scope"
        },
        "ot": {
          "description": "Whether this is an OT discovery scope",
          "type": "boolean"
        },
        "scope_id": {
          "description": "Set if EXISTING scope shall be updated",
          "type": "integer",
          "example": 42
        },
        "split_size": {
          "description": "Maximum amount of IPs per split scan target",
          "type": "integer",
          "example": 2048
        },
        "targets": {
          "description": "List of scan targets to set",
          "type": "array",
          "items": {
            "$ref": "#/definitions/scopedb.T_discovery"
          }
        }
      }
    },
    "handlers.ScopeCreateUpdateCustomResponse": {
      "type": "object",
      "properties": {
        "warnings": {
          "description": "List of warnings generated during target processing",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "handlers.ScopeTargetsRequest": {
      "type": "object",
      "properties": {
        "id": {
          "description": "Scope ID to get the targets for",
          "type": "integer",
          "example": 42
        }
      }
    },
    "handlers.ScopeTargetsResponse": {
      "type": "object",
      "properties": {
        "synchronization": {
          "description": "Flag indicating whether previous synchronization is still ongoing (no targets in that case)",
          "type": "boolean"
        },
        "targets": {
          "description": "Only returned if no synchronization currently ongoing",
          "type": "array",
          "items": {
            "$ref": "#/definitions/scopedb.T_discovery"
          }
        }
      }
    },
    "handlers.ScopesResponse": {
      "type": "object",
      "properties": {
        "allow_asset": {
          "description": "Whether the user is allowed to create asset scan scopes",
          "type": "boolean"
        },
        "allow_custom": {
          "description": "Whether the user is allowed to create custom scan scopes",
          "type": "boolean"
        },
        "allow_network": {
          "description": "Whether the user is allowed to create network scan scopes",
          "type": "boolean"
        },
        "scopes": {
          "description": "List of scan scopes owned by the current user",
          "type": "array",
          "items": {
            "$ref": "#/definitions/handlers.Scope"
          }
        }
      }
    },
    "scopedb.T_discovery": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "input": {
          "type": "string"
        },
        "input_comment": {
          "description": "E.g. anything that helps",
          "type": "string"
        },
        "input_company": {
          "description": "E.g. company name, useful in a multi company network",
          "type": "string"
        },
        "input_contact": {
          "description": "E.g. the responsible administrator",
          "type": "string"
        },
        "input_country": {
          "description": "E.g. \"DE\"",
          "type": "string"
        },
        "input_department": {
          "description": "E.g. company department, e.g. IT Services",
          "type": "string"
        },
        "input_location": {
          "description": "E.g. \"Munich\"",
          "type": "string"
        },
        "input_manager": {
          "description": "E.g. the responsible manager",
          "type": "string"
        },
        "input_network": {
          "description": "Network the input address belongs to. Equals input if input is already a network range",
          "type": "string"
        },
        "input_purpose": {
          "description": "E.g. network description, like, \"transfer network\", \"office space\",...",
          "type": "string"
        },
        "input_routing_domain": {
          "description": "E.g. \"Global\", \"local\", \"Intranet\", \"Internet\",...",
          "type": "string"
        },
        "input_zone": {
          "description": "E.g. \"Office\", \"Production A\", \"Printer\",...",
          "type": "string"
        },
        "lat": {
          "type": "string"
        },
        "lng": {
          "type": "string"
        },
        "postal_address": {
          "type": "string"
        },
        "priority": {
          "type": "boolean"
        },
        "scan_finished": {
          "$ref": "#/definitions/sql.NullTime"
        },
        "scan_started": {
          "$ref": "#/definitions/sql.NullTime"
        },
        "timezone": {
          "description": "Float because timezones may be 11.5 in certain edge cases",
          "type": "number"
        }
      }
    },
    "sql.NullTime": {
      "type": "object",
      "properties": {
        "time": {
          "type": "string"
        },
        "valid": {
          "description": "Valid is true if Time is not NULL",
          "type": "boolean"
        }
      }
    },
    "utils.JsonMap": {
      "type": "object",
      "additionalProperties": true
    },
    "utils.Timespan": {
      "type": "object",
      "properties": {
        "endDay": {
          "type": "string"
        },
        "endTime": {
          "type": "string"
        },
        "startDay": {
          "type": "string"
        },
        "startTime": {
          "type": "string"
        }
      }
    }
  },
  "securityDefinitions": {
    "BearerAuth": {
      "type": "apiKey",
      "name": "Authorization",
      "in": "header"
    }
  }
}