package tsunami.proto

Get desktop application:
View/edit binary Protocol Buffers messages

Represents the plugin service, two RPCs for running plugins and listing plugins, respectively.

• rpc Run (RunRequest, RunResponse)

  plugin_service.proto:97

  Performs a run request to run all language plugins specified by the request.

  message RunRequest

  plugin_service.proto:34

  Represents a run request with all matched plugins that will need to run as well as the target to run against.

  • optional TargetInfo target = 1

    Target of the plugins.

  • repeated MatchedPlugin plugins = 2

    All matched plugins that will need to run.

• rpc RunCompact (RunCompactRequest, RunResponse)

  plugin_service.proto:103

  Performs a run request to run all language plugins specified by the compact representation of the request. This is useful, when hundreds of plugins are to be run against many different NetworkServices. The language server must set `want_compact_run_request` so that the Tsunami CLI knows to invoke this method instead of `Run`.

  message RunCompactRequest

  plugin_service.proto:42

  Compact representation of RunRequest.

  • optional TargetInfo target = 1

    Target of the plugins.

  • repeated NetworkService services = 2

    All network services that are targeted by some of the plugins.

  • repeated PluginDefinition plugins = 3

    All plugins that should be executed during the run.

  • repeated RunCompactRequest.PluginNetworkServiceTarget scan_targets = 4

    The concrete map of plugin/network service pairs that should be scanned.

• rpc ListPlugins (ListPluginsRequest, ListPluginsResponse)

  plugin_service.proto:105

  Sends a request to list all plugins from the respective language server.

  message ListPluginsRequest

  plugin_service.proto:80

  Represents a request to list all plugins from the requested server.

  (message has no fields)

  message ListPluginsResponse

  plugin_service.proto:84

  Represents a response containing a list of all plugins from the requested server.

  • repeated PluginDefinition plugins = 1

  • bool want_compact_run_request = 2

    Plugin service can indicate here that it RunRequest should be compact (compact_targets should be populated instead of MatchedPlugin plugins).

Additional details regarding a vulnerability can be stored here. Prefers to use the existing structured data when possible, otherwise store the raw data as a blob.

Used in: Vulnerability

• string description = 1

• oneof detail

  • BlobData blob_data = 2

  • TextData text_data = 3

  • Credential credential = 4

  • Credentials credentials = 5

The address family of an IP address.

Used in: IpAddress

• ADDRESS_FAMILY_UNSPECIFIED = 0

• IPV4 = 4

• IPV6 = 6

A piece of arbitrary binary data.

Used in: AdditionalDetail

• bytes data = 1

Next ID: 7

• repeated string seeding_urls = 1

  Starting points of a web crawl. Required.

• int32 max_depth = 2

  The maximum depth of a web crawl. Required.

• repeated CrawlConfig.Scope scopes = 3

  Allowed crawling scopes. Optional. When empty, scopes are autogenerated from seeding_urls.

• bool should_enforce_scope_check = 5

  Whether crawling scope check should be enforced. Optional.

• optional NetworkEndpoint network_endpoint = 6

  The network endpoint to be crawled. Required.

The crawler should only interact with web resources under certain scopes.

Used in: CrawlConfig

• string domain = 1

  The domain of the scope, only URLs that are on the same domain or a subdomain will be admitted for crawling. Domain might include a port. Required.

• string path = 2

  The path of the scope, only URLs that are under the same path will be admitted for crawling. Optional. When empty, all URLs under the same domain are allowed, regardless of the paths.

Used in: WebServiceContext

• optional CrawlTarget crawl_target = 1

  The target visited by the crawler.

• int32 crawl_depth = 2

  Depth at which the target was visited.

• int32 response_code = 3

  Response code from the crawled target.

• string content_type = 4

  Content type of the resource served at the crawl target.

• bytes content = 5

  The content of the resource served at the crawl target.

• repeated HttpHeader response_headers = 6

  Http headers of the response

Used in: CrawlResult

• string url = 1

  The URL pointing to the document.

• string http_method = 2

  HTTP method to reach the url. Value must be in all upper case, like "GET".

• bytes http_request_body = 3

  An optional HTTP request body sent to the crawl URL.

Credential for a vulnerable network service.

Used in: AdditionalDetail, Credentials

• string username = 1

• string password = 2

A set of credentials for a vulnerable network service.

Used in: AdditionalDetail

• repeated Credential credential = 1

Full report about a detected vulnerability.

Used in: DetectionReportList, FullDetectionReports

• optional TargetInfo target_info = 1

  Information about the scanned target.

• optional NetworkService network_service = 2

  Information about the scanned network service.

• optional google.protobuf.Timestamp detection_timestamp = 3

  Time when the vulnerability was detected.

• DetectionStatus detection_status = 4

  Status of the detection result.

• optional Vulnerability vulnerability = 5

  Full details about the detected vulnerability.

Used in: RunResponse

• repeated DetectionReport detection_reports = 1

Status of the vulnerability detection result.

Used in: DetectionReport

• DETECTION_STATUS_UNSPECIFIED = 0

  Unspecified status.

• SAFE = 1

  Target is not vulnerable.

• VULNERABILITY_PRESENT = 2

  Target appears to be vulnerable (e.g. because running version is vulnerable), but couldn't be verified.

• VULNERABILITY_VERIFIED = 3

  Target is vulnerable and the detector successfully verified the vulnerability.

Report from a service fingerprinter.

• repeated NetworkService network_services = 3

  List of all the identified network services after fingerprinting.

Full detection reports from all triggered Tsunami detection plugins.

Used in: ScanResults

• repeated DetectionReport detection_reports = 1

The hostname of a networking device.

Used in: NetworkEndpoint

• string name = 1

Represents an HTTP header.

Used in: CrawlResult

• string key = 1

• string value = 2

The IP address of a networking device.

Used in: NetworkEndpoint

• AddressFamily address_family = 1

  The family of the IP address.

• string address = 2

  A human-readable representation of the IP address, e.g. 127.0.0.1 for IPV4 and 2001:db8:0:1234:0:567:8:1 for IPV6.

Represents the plugin needed to run by the language-specific server as well as all the matched network services for the plugin.

Used in: RunRequest

• repeated NetworkService services = 1

  All matched network services from the reconnaissance report.

• optional PluginDefinition plugin = 2

  Plugin to run.

A classification of an endpoint for a network device.

Used in: CrawlConfig, NetworkService, ScanTarget, TargetInfo

• NetworkEndpoint.Type type = 1

  Type of the network endpoint.

• optional IpAddress ip_address = 2

  Optional IP address of a network endpoint. Must be specified when Type is IP or IP_PORT.

• optional Port port = 3

  Optional port of a network endpoint. Must be specified when Type is IP_PORT or HOSTNAME_PORT.

• optional Hostname hostname = 4

  Optional hostname of a network endpoint. Must be specified when Type is HOSTNAME or HOSTNAME_PORT.

Used in: NetworkEndpoint

• TYPE_UNSPECIFIED = 0

• IP = 1

  The network endpoint is represented by an IP address.

• IP_PORT = 2

  The network endpoint is represented by IP address and port pair.

• HOSTNAME = 3

  The network endpoint is represented by a hostname.

• HOSTNAME_PORT = 4

  The network endpoint is represented by a hostname and port pair.

• IP_HOSTNAME = 5

  The network endpoint is represented by an IP address and hostname.

• IP_HOSTNAME_PORT = 6

  The network endpoint is represented by an IP address, hostname and port.

General information about a network service running on a target.

Used in: DetectionReport, FingerprintingReport, MatchedPlugin, PortScanningReport, ReconnaissanceReport, RunCompactRequest, ScanFinding, ScanTarget

• optional NetworkEndpoint network_endpoint = 1

  The network endpoint where this network service is served.

• TransportProtocol transport_protocol = 2

  The transport layer protocol used by the service.

• string service_name = 3

  The name of the network service, following convention in RFC6335. Examples are like http, telnet, ssh, etc.

• optional Software software = 4

  The software that provides the service behind the port.

• optional VersionSet version_set = 5

  The complete set of versions of the software.

• repeated string banner = 6

  Banners generated by the service.

• optional ServiceContext service_context = 7

  Context information about this network service.

• repeated string cpes = 8

  The detected Common Platform Enumeration (CPE) name for service, in the uri binding representation, like: cpe:/a:openbsd:openssh:8.4p1

• repeated string supported_ssl_versions = 9

  List of supported SSL versions (e.g. TLSv1, SSLv3, ...) on the service.

• repeated string supported_http_methods = 10

  List of supported HTTP methods (e.g. POST, GET, ...) on the service.

Represents a ForOperatingSystem annotation placeholder used by the PluginDefinition proto above. For possible values, consult the following database: https://raw.githubusercontent.com/nmap/nmap/master/nmap-os-db

Used in: TargetInfo

• string type = 1

  The type of the target operating system, e.g. "general purpose"

• string vendor = 2

  The vendor of the target operating system, e.g. "Linux"

• string os_family = 3

  The family of the target operating system, e.g. "Linux"

• string os_generation = 4

  The generation of the target operating system, e.g. "2.6.X"

• uint32 accuracy = 5

  The estimated accuracy of the target operating system, e.g. 90

Attributes of a payload. A detector can check these attributes to change its logic based on the payload type.

• bool uses_callback_server = 1

  Whether the payload uses the callback server

Schema for each entry in payload_definitions.yaml Note: this message uses StringValue and BoolValue because we validate whether each payload definition in the yaml file has the correct fields present. Since empty proto fields are given default values (proto fields are not nullable), we use the wrapped types to check for actual presence.

Used in: PayloadLibrary

• optional google.protobuf.StringValue name = 1

  The human-readable string to identify the payload

• PayloadGeneratorConfig.InterpretationEnvironment interpretation_environment = 2

• PayloadGeneratorConfig.ExecutionEnvironment execution_environment = 3

• repeated PayloadGeneratorConfig.VulnerabilityType vulnerability_type = 4

  All vulnerability types this payload can be used for

• optional google.protobuf.BoolValue uses_callback_server = 5

  If true, payload_string must contain the $TSUNAMI_PAYLOAD_TOKEN_URL token. Validation will automatically check against the callback server, so the validation* fields do not need to be set.

• optional google.protobuf.StringValue payload_string = 6

  The actual payload command string. The following special tokens can be used which will cause the framework to inject dynamic content into the command: - $TSUNAMI_PAYLOAD_TOKEN_URL: url for the callback server - a random string, used to reduce false positives.

• PayloadValidationType validation_type = 7

  The type of validation function for determining if the payload was executed. Currently, only REGEX is supported.

• optional google.protobuf.StringValue validation_regex = 8

  Required if validation_type == REGEX. Must be compatible with java.util.regex.Pattern. The string will first be preprocessed before applied as a regex, replacing any of the following tokens with the corresponding values supplied by the framework: - $TSUNAMI_PAYLOAD_TOKEN_RANDOM: a random string, used to reduce false positives. The value is guaranteed to be the same as the value supplied to payload_string.

Attributes utilized by the PayloadGenerator to select a payload

• PayloadGeneratorConfig.VulnerabilityType vulnerability_type = 2

• PayloadGeneratorConfig.InterpretationEnvironment interpretation_environment = 3

• PayloadGeneratorConfig.ExecutionEnvironment execution_environment = 4

The actual runtime environment when the payload is run e.g. while a PHP-based target wants a PHP-interpretation environment, the actual code execution may happen via the Linux shell: exec(“echo \”this is running in the system.\””).

Used in: PayloadDefinition, PayloadGeneratorConfig

• EXECUTION_ENVIRONMENT_UNSPECIFIED = 0

  Unspecified execution environment type

• EXEC_INTERPRETATION_ENVIRONMENT = 1

  Execute within the InterpretationEnvironment

• EXEC_ANY = 2

  Execution environment doesn't matter

The environment that processes the payload for execution e.g. a PHP-based target likely wants a payload that is itself PHP code.

Used in: PayloadDefinition, PayloadGeneratorConfig

• INTERPRETATION_ENVIRONMENT_UNSPECIFIED = 0

  Unspecified interpretation environment type

• LINUX_SHELL = 1

  Payload is interpreted within a Linux shell environment

• JAVA = 2

  Payload is interpreted wihin a Java compiler context

• PHP = 3

  Payload is interpreted wihin a PHP VM context

• INTERPRETATION_ANY = 4

  Interpretation environment doesn't matter

• LINUX_ROOT_CRONTAB = 5

  Payload is interpreted wihin crontab

• WINDOWS_SHELL = 6

  Payload is interpreted wihin a Windows shell environment

• JSP = 7

  Payload is interpreted within a JSP shell environment

The type of vulnerability the detector is looking for

Used in: PayloadDefinition, PayloadGeneratorConfig

• VULNERABILITY_TYPE_UNSPECIFIED = 0

  Unspecified vulnerability type

• REFLECTIVE_RCE = 1

  RCE which returns the output of the execution

• BLIND_RCE = 2

  RCE which does not return the output of the execution

• SSRF = 3

  Server-Side Request Forgery

• ARBITRARY_FILE_WRITE = 4

  Arbitrary File Write

• BLIND_RCE_FILE_READ = 5

  RCE without output of the execution + File Read (needed to get confirmation string)

Container type for payload_definitions.yaml

• repeated PayloadDefinition payloads = 1

Used in: PayloadDefinition

• VALIDATION_TYPE_UNSPECIFIED = 0

• VALIDATION_REGEX = 1

Represents a PluginDefinition placeholder.

Used in: ListPluginsResponse, MatchedPlugin, RunCompactRequest

• optional PluginInfo info = 1

  PluginInfo of this definition.

• optional TargetServiceName target_service_name = 2

  The name of the target service.

• optional TargetSoftware target_software = 3

  The name of the target software.

• bool for_web_service = 4

  If the definition is for a web service or not.

• optional TargetOperatingSystemClass target_operating_system_class = 5

  If the definition is for a specific operating system or not. Note: this filter is executed within an AND condition with the other filters. E.g. if target_service_name.value is "http" and target_operating_system.osclass.family is "Linux" then the plugin will only match if the service is http and the operating system is Linux.

Represents a PluginInfo annotation placeholder used by the PluginDefinition proto above.

Used in: PluginDefinition

• PluginInfo.PluginType type = 1

  Type of plugin.

• string name = 2

  Name of the plugin.

• string version = 3

  Version of the plugin

• string description = 4

  Description of the plugin.

• string author = 5

  Author of the plugin.

Used in: PluginInfo

• PLUGIN_TYPE_UNSPECIFIED = 0

  Plugin is an unspecified type.

• PORT_SCAN = 1

  Plugin is a port scanner.

• SERVICE_FINGERPRINT = 2

  Plugin is a service fingerprinter.

• VULN_DETECTION = 3

  Plugin is a vulnerability detector.

The port that a network service listens to.

Used in: NetworkEndpoint

• uint32 port_number = 1

Report from a port scanner.

• optional TargetInfo target_info = 1

  Information about the scanning target.

• repeated NetworkService network_services = 2

  List of all the exposed network services.

Full reconnaissance report about a single scanning target.

Used in: ScanResults

• optional TargetInfo target_info = 1

  Information about the scanning target.

• repeated NetworkService network_services = 2

  All exposed network services of the scanning target.

Indexes in the following structure point to the services/plugins defined below. (The order is safe, guaranteed by the proto specification: "The order of the elements with respect to each other is preserved when parsing, though the ordering with respect to other fields is lost.")

Used in: RunCompactRequest

• uint32 plugin_index = 1

  The index of the plugin to run.

• uint32 service_index = 2

  The index of the network service to run against.

Represents a run response with the only field being all DetectionReports generated by the language-specific server.

Used as response type in: PluginService.Run, PluginService.RunCompact

• optional DetectionReportList reports = 1

A single vulnerability finding for a specific service.

Used in: ScanResults

• optional TargetInfo target_info = 1

  Information about the scanned target.

• optional NetworkService network_service = 2

  Information about the scanned network service.

• optional Vulnerability vulnerability = 3

  Details about the detected vulnerability.

Full scanning results. NEXT ID: 9

• ScanStatus scan_status = 1

  Status of this scan.

• string status_message = 6

  Detailed message for the scan status.

• bool target_alive = 8

  Reports whether the target was alive during the scan. A target is considered alive if at least one network service was identified or at least one vulnerability was detected.

• repeated ScanFinding scan_findings = 2

  All findings from this scan.

• optional google.protobuf.Timestamp scan_start_timestamp = 3

  Time when this scan was started.

• optional google.protobuf.Duration scan_duration = 4

  Duration of the full scan.

• optional FullDetectionReports full_detection_reports = 5

  Detection reports from all triggered Tsunami detection plugins.

• optional ReconnaissanceReport reconnaissance_report = 7

  Reconnaissance reports from the fingerprinting stage.

Execution status of the scan. NEXT ID: 5

Used in: ScanResults

• SCAN_STATUS_UNSPECIFIED = 0

  Unspecified status.

• SUCCEEDED = 1

  Scan finished successfully.

• PARTIALLY_SUCCEEDED = 4

  Scan finished with only a small set of selected detectors succeeded.

• FAILED = 2

  Scan failed.

• CANCELLED = 3

  Scan cancelled.

The information about a scan target.

• oneof target

  • NetworkEndpoint network_endpoint = 1

    The network endpoint to be scanned.

  • NetworkService network_service = 2

    The network service to be scanned.

Context information about a specific network service.

Used in: NetworkService

• oneof context

  • WebServiceContext web_service_context = 1

Severity of a vulnerability.

Used in: Vulnerability

• SEVERITY_UNSPECIFIED = 0

  Unspecified severity.

• MINIMAL = 1

  Minimal severity.

• LOW = 2

  Low severity.

• MEDIUM = 3

  Medium severity.

• HIGH = 4

  High severity.

• CRITICAL = 5

  Critical severity.

A structured description about a software.

Used in: NetworkService, WebServiceContext

• string name = 1

  The name of this software.

Detailed information about the scanning target.

Used in: DetectionReport, PortScanningReport, ReconnaissanceReport, RunCompactRequest, RunRequest, ScanFinding

• repeated NetworkEndpoint network_endpoints = 1

  All the known network endpoints of the scanning target.

• repeated OperatingSystemClass operating_system_classes = 2

Represents a ForOperatingSystem annotation placeholder used by the PluginDefinition proto above. These values are coming directly from the port scanner's output (e.g. nmap).

Used in: PluginDefinition

• repeated string vendor = 1

  The vendor of the target operating system, e.g. "Microsoft"

• repeated string os_family = 2

  The family of the target operating system, e.g. "Windows"

• uint32 min_accuracy = 3

  The minimum accuracy of the target operating system, e.g. 90

Represents a ForServiceName annotation placeholder used by the PluginDefinition proto above.

Used in: PluginDefinition

• repeated string value = 1

  The value of the name of the target.

Represents a ForSoftware annotation placeholder used by the PluginDefinition proto above.

Used in: PluginDefinition

• string name = 1

  The name of the target software, case insensitive.

• repeated string value = 2

  Array of versions and version ranges of the target software.

A piece of arbitrary UTF-8 encoded text data.

Used in: AdditionalDetail

• string text = 1

The transport layer protocols.

Used in: NetworkService

• TRANSPORT_PROTOCOL_UNSPECIFIED = 0

• TCP = 1

• UDP = 2

• SCTP = 3

The exact version of a software.

Used in: VersionRange, VersionSet

• Version.VersionType type = 1

  Distinguishes between sentinel MIN/MAX versions and normal versions.

• string full_version_string = 2

  Human readable version number, e.g. 1.0.3. This is set only when type is NORMAL. Tsunami uses raw string to represent a version number instead of any structured messages in order to handle different kinds of version schemes. Tsunami will tokenize this version string and store tokens internally. When performing version comparisons, Tsunami follows the precedence defined by Semantic Versioning (semver.org). More details can be found in Tsunami's internal Version class.

Type of the Version message, identifying an ordinary software version or a sentinel MINIMUM/MAXIMUM version. See comments below for what is a sentinel version.

Used in: Version

• VERSION_TYPE_UNSPECIFIED = 0

• NORMAL = 1

  A normal software version.

• MINIMUM = 2

  A sentinel version representing negative infinity, i.e. MINIMUM version is less than any NORMAL and MAXIMUM versions.

• MAXIMUM = 3

  A sentinel version representing positive infinity, i.e. MAXIMUM version is greater than any NORMAL and MINIMUM versions.

An inclusive range of versions for a software.

Used in: VersionSet

• optional Version min_version = 1

  Minimum version that belongs in the range.

• VersionRange.Inclusiveness min_version_inclusiveness = 2

  Inclusiveness of the min_version. When min_version points to negative infinity, this value will always be EXCLUSIVE to matching the representation of (-inf, 1.0]. Note that negative infinity version should ***NOT*** be compared with a version range as it is just a bogus sentinel version without any meaning.

• optional Version max_version = 3

  Maximum version that belongs in the range.

• VersionRange.Inclusiveness max_version_inclusiveness = 4

  Inclusiveness of the max_version. When max_version points to positive infinity, this value will always be EXCLUSIVE to matching the representation of [1.0, inf). Note that positive infinity version should ***NOT*** be compared with a version range as it is just a bogus sentinel version without any meaning.

Whether the range endpoint is inclusive or exclusive.

Used in: VersionRange

• INCLUSIVENESS_UNSPECIFIED = 0

• INCLUSIVE = 1

• EXCLUSIVE = 2

A set of Versions and VersionRanges that completely describes a set of software releases, e.g. {3.9.1, 3.9.3, [4.7.1, 4.7.8], 4.8}

Used in: NetworkService, WebServiceContext

• repeated Version versions = 1

• repeated VersionRange version_ranges = 2

Message that represents one single vulnerability detected by Tsunami.

Used in: DetectionReport, ScanFinding

• optional VulnerabilityId main_id = 1

  The main identifier for this vulnerability, usually a publicly known identifier like CVEs and such. If not publicly known, users are expected to assign an id on their own.

• repeated VulnerabilityId related_id = 2

  Any related identifiers about this vulnerability, e.g. a CWE weakness.

• Severity severity = 3

  Severity of this vulnerability.

• string title = 4

  Terse but descriptive sentence about this vulnerability. For example: "Default Password (0p3nm35h) for 'root' Account.".

• string description = 5

  Verbose description of this vulnerability.

• string recommendation = 6

  Optional. Verbose recommended solution(s).

• string cvss_v2 = 7

  Optional. The CVSS v2 score of this vulnerability.

• string cvss_v3 = 8

  Optional. The CVSS v3 score of this vulnerability.

• repeated AdditionalDetail additional_details = 9

  Any additional technical details about this vulnerability.

The identifier that uniquely identifies this vulnerability.

Used in: Vulnerability

• string publisher = 1

  Entity that published this identifier.

• string value = 2

  Publisher assigned unique identifier.

• string link = 3

  Optional. URL for details about this vulnerability.

Context information about a web application. NEXT ID: 5

Used in: ServiceContext

• string application_root = 1

  The root path of the hosted web application.

• optional Software software = 2

  The web application that is serving under the application root.

• optional VersionSet version_set = 3

  The detected versions of the web application.

• repeated CrawlResult crawl_results = 4

  Fingerprinter's crawling results for this web service.