openapi: 3.1.0
info:
  title: Tufin SecureTrack REST API
  description: >-
    The Tufin SecureTrack REST API enables programmatic access to network security
    policy management across multi-vendor firewall infrastructure. It provides endpoints
    for querying network devices, analyzing firewall rules and policies, performing network
    topology analysis, executing path queries, managing rule documentation, and retrieving
    compliance and risk analysis data. Authentication uses HTTP Basic Auth with Tufin
    Orchestration Suite (TOS) credentials.
  version: R25-2
  contact:
    name: Tufin Support
    url: https://www.tufin.com/support
  license:
    name: Tufin Terms of Use
    url: https://www.tufin.com/terms-of-use
externalDocs:
  description: Tufin SecureTrack REST API Documentation
  url: https://forum.tufin.com/support/kc/latest/Content/Suite/RESTAPI/securetrack_api.htm
servers:
  - url: https://{tos_host}/securetrack/api
    description: Tufin Orchestration Suite Server
    variables:
      tos_host:
        description: Hostname or IP address of the TOS server
        default: tufin.example.com
tags:
  - name: Devices
    description: Manage network devices and firewalls
  - name: Rules
    description: Query and manage firewall rules and policies
  - name: Topology
    description: Network topology analysis and path queries
  - name: Objects
    description: Network objects, services, and address groups
  - name: Compliance
    description: Policy compliance and risk analysis
  - name: Revisions
    description: Device policy revisions and change history
  - name: Zones
    description: Security zones and zone-to-zone matrix
paths:
  /devices:
    get:
      operationId: getDevices
      summary: Get All Devices
      description: >-
        Retrieve all network devices (firewalls, routers) managed by SecureTrack,
        optionally filtered by name, vendor, or management status.
      tags:
        - Devices
      security:
        - basicAuth: []
      parameters:
        - name: name
          in: query
          description: Filter by device name (partial match)
          schema:
            type: string
        - name: vendor
          in: query
          description: Filter by vendor (e.g., Cisco, Palo Alto, Check Point)
          schema:
            type: string
        - name: type
          in: query
          description: Filter by device type
          schema:
            type: string
        - name: status
          in: query
          description: Filter by management status
          schema:
            type: string
      responses:
        '200':
          description: List of devices
          content:
            application/json:
              schema:
                type: object
                properties:
                  devices:
                    type: object
                    properties:
                      count:
                        type: integer
                      device:
                        type: array
                        items:
                          $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized
  /devices/{deviceId}:
    get:
      operationId: getDeviceById
      summary: Get Device By ID
      description: Retrieve a specific network device by its identifier.
      tags:
        - Devices
      security:
        - basicAuth: []
      parameters:
        - name: deviceId
          in: path
          required: true
          description: The unique identifier of the device
          schema:
            type: integer
      responses:
        '200':
          description: Device details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '404':
          description: Device not found
    put:
      operationId: updateDevice
      summary: Update Device
      description: Update an offline device's configuration.
      tags:
        - Devices
      security:
        - basicAuth: []
      parameters:
        - name: deviceId
          in: path
          required: true
          description: The unique identifier of the device
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceInput'
      responses:
        '200':
          description: Device updated
  /devices/{deviceId}/revisions:
    get:
      operationId: getDeviceRevisions
      summary: Get Device Revisions
      description: Retrieve the list of policy revisions for a device.
      tags:
        - Devices
        - Revisions
      security:
        - basicAuth: []
      parameters:
        - name: deviceId
          in: path
          required: true
          description: The unique identifier of the device
          schema:
            type: integer
      responses:
        '200':
          description: List of revisions
          content:
            application/json:
              schema:
                type: object
                properties:
                  revisions:
                    type: object
                    properties:
                      revision:
                        type: array
                        items:
                          $ref: '#/components/schemas/Revision'
  /devices/{deviceId}/rules:
    get:
      operationId: getRulesByDevice
      summary: Get Rules By Device
      description: Retrieve all firewall rules for a specific device.
      tags:
        - Devices
        - Rules
      security:
        - basicAuth: []
      parameters:
        - name: deviceId
          in: path
          required: true
          description: The unique identifier of the device
          schema:
            type: integer
        - name: policy
          in: query
          description: Filter by policy name
          schema:
            type: string
      responses:
        '200':
          description: List of rules
          content:
            application/json:
              schema:
                type: object
                properties:
                  rules:
                    type: object
                    properties:
                      count:
                        type: integer
                      rule:
                        type: array
                        items:
                          $ref: '#/components/schemas/Rule'
  /devices/{deviceId}/rules/{ruleId}:
    get:
      operationId: getRuleByDeviceAndId
      summary: Get Rule By Device and ID
      description: Retrieve a specific firewall rule by device and rule ID.
      tags:
        - Devices
        - Rules
      security:
        - basicAuth: []
      parameters:
        - name: deviceId
          in: path
          required: true
          description: The unique identifier of the device
          schema:
            type: integer
        - name: ruleId
          in: path
          required: true
          description: The unique identifier of the rule
          schema:
            type: integer
      responses:
        '200':
          description: Rule details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '404':
          description: Rule not found
  /devices/offline:
    post:
      operationId: addOfflineDevice
      summary: Add Offline Device
      description: Add an offline device to SecureTrack management.
      tags:
        - Devices
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceInput'
      responses:
        '200':
          description: Offline device added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
  /topology/path:
    get:
      operationId: getTopologyPath
      summary: Get Network Path
      description: >-
        Query the network topology to determine whether traffic is permitted between
        source and destination endpoints, and which devices are traversed.
      tags:
        - Topology
      security:
        - basicAuth: []
      parameters:
        - name: src
          in: query
          required: true
          description: Source IP address or CIDR range
          schema:
            type: string
        - name: dst
          in: query
          required: true
          description: Destination IP address or CIDR range
          schema:
            type: string
        - name: service
          in: query
          description: Service (protocol/port, e.g., tcp/443)
          schema:
            type: string
      responses:
        '200':
          description: Path analysis result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopologyPath'
  /topology/path/image:
    get:
      operationId: getTopologyPathImage
      summary: Get Topology Path Image
      description: Export a visualization of the network path as a PNG image.
      tags:
        - Topology
      security:
        - basicAuth: []
      parameters:
        - name: src
          in: query
          required: true
          description: Source IP address or CIDR range
          schema:
            type: string
        - name: dst
          in: query
          required: true
          description: Destination IP address or CIDR range
          schema:
            type: string
      responses:
        '200':
          description: Path topology image
          content:
            image/png:
              schema:
                type: string
                format: binary
  /topology/map:
    get:
      operationId: getTopologyMap
      summary: Get Topology Map
      description: Retrieve the full network topology map.
      tags:
        - Topology
      security:
        - basicAuth: []
      responses:
        '200':
          description: Topology map data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopologyMap'
  /network_objects:
    get:
      operationId: getNetworkObjects
      summary: Get Network Objects
      description: Search for network objects (hosts, ranges, groups) across all managed devices.
      tags:
        - Objects
      security:
        - basicAuth: []
      parameters:
        - name: name
          in: query
          description: Filter by object name
          schema:
            type: string
        - name: ip
          in: query
          description: Filter by IP address
          schema:
            type: string
        - name: type
          in: query
          description: Filter by object type (host, range, group)
          schema:
            type: string
      responses:
        '200':
          description: List of network objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  network_objects:
                    type: object
                    properties:
                      count:
                        type: integer
                      network_object:
                        type: array
                        items:
                          $ref: '#/components/schemas/NetworkObject'
  /services:
    get:
      operationId: getServices
      summary: Get Services
      description: Search for service objects (protocols and ports) across all managed devices.
      tags:
        - Objects
      security:
        - basicAuth: []
      parameters:
        - name: name
          in: query
          description: Filter by service name
          schema:
            type: string
        - name: port
          in: query
          description: Filter by port number
          schema:
            type: string
      responses:
        '200':
          description: List of services
          content:
            application/json:
              schema:
                type: object
                properties:
                  services:
                    type: object
                    properties:
                      service:
                        type: array
                        items:
                          $ref: '#/components/schemas/Service'
  /zones:
    get:
      operationId: getZones
      summary: Get Security Zones
      description: Retrieve all security zones defined across managed devices.
      tags:
        - Zones
      security:
        - basicAuth: []
      responses:
        '200':
          description: List of security zones
          content:
            application/json:
              schema:
                type: object
                properties:
                  zones:
                    type: object
                    properties:
                      zone:
                        type: array
                        items:
                          $ref: '#/components/schemas/Zone'
  /risk:
    get:
      operationId: getRiskAnalysis
      summary: Get Risk Analysis
      description: Retrieve risk analysis findings including policy violations and cleanup tasks.
      tags:
        - Compliance
      security:
        - basicAuth: []
      parameters:
        - name: device_id
          in: query
          description: Filter by device ID
          schema:
            type: integer
      responses:
        '200':
          description: Risk analysis results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RiskFinding'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using Tufin Orchestration Suite credentials.
        The authenticated user's TOS permissions apply to all API requests.
  schemas:
    Device:
      type: object
      description: A network device managed by SecureTrack
      properties:
        id:
          type: integer
          description: Unique identifier of the device
        name:
          type: string
          description: Display name of the device
        ip:
          type: string
          description: Management IP address
        vendor:
          type: string
          description: Device vendor (e.g., Cisco, Palo Alto Networks, Check Point)
        model:
          type: string
          description: Device model
        version:
          type: string
          description: Software version
        domain:
          type: string
          description: Management domain
        topology:
          type: boolean
          description: Whether this device participates in topology analysis
        managedBy:
          type: string
          description: Management system (e.g., Panorama, SmartCenter)
    DeviceInput:
      type: object
      description: Input for adding or updating a device
      required:
        - vendor
        - model
        - name
      properties:
        vendor:
          type: string
          description: Device vendor
        model:
          type: string
          description: Device model
        name:
          type: string
          description: Device display name
        ip:
          type: string
          description: Management IP address
    Revision:
      type: object
      description: A policy revision for a device
      properties:
        id:
          type: integer
          description: Revision identifier
        device_id:
          type: integer
          description: Device this revision belongs to
        date:
          type: string
          format: date-time
          description: When this revision was recorded
        description:
          type: string
          description: Description of changes in this revision
    Rule:
      type: object
      description: A firewall rule on a network device
      properties:
        id:
          type: integer
          description: Rule identifier
        name:
          type: string
          description: Rule name
        enabled:
          type: boolean
          description: Whether the rule is enabled
        action:
          type: string
          description: Rule action (ACCEPT, DROP, REJECT)
          enum:
            - ACCEPT
            - DROP
            - REJECT
        sources:
          type: array
          items:
            $ref: '#/components/schemas/NetworkObject'
          description: Source network objects
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/NetworkObject'
          description: Destination network objects
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'
          description: Services this rule applies to
        comment:
          type: string
          description: Rule comment or documentation
        lastHit:
          type: string
          format: date-time
          description: Last time this rule was matched
    TopologyPath:
      type: object
      description: Result of a network topology path query
      properties:
        traffic_allowed:
          type: boolean
          description: Whether traffic is allowed between source and destination
        is_fully_routed:
          type: boolean
          description: Whether a complete routed path exists
        device_info:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Device name
              id:
                type: integer
                description: Device ID
          description: Devices traversed in the path
    TopologyMap:
      type: object
      description: Network topology map data
      properties:
        nodes:
          type: array
          items:
            type: object
          description: Topology nodes (devices, subnets)
        edges:
          type: array
          items:
            type: object
          description: Topology connections between nodes
    NetworkObject:
      type: object
      description: A network object (host, range, or group)
      properties:
        id:
          type: integer
          description: Object identifier
        name:
          type: string
          description: Object name
        type:
          type: string
          description: Object type (host, range, group)
        ip:
          type: string
          description: IP address or range
        netmask:
          type: string
          description: Network mask
    Service:
      type: object
      description: A service object (protocol/port combination)
      properties:
        id:
          type: integer
          description: Service identifier
        name:
          type: string
          description: Service name
        protocol:
          type: string
          description: Protocol (TCP, UDP, ICMP)
        port:
          type: string
          description: Port number or range
    Zone:
      type: object
      description: A security zone
      properties:
        id:
          type: integer
          description: Zone identifier
        name:
          type: string
          description: Zone name
        comment:
          type: string
          description: Zone description
        subnets:
          type: array
          items:
            type: string
          description: IP subnets belonging to this zone
    RiskFinding:
      type: object
      description: A risk analysis finding
      properties:
        rule_id:
          type: integer
          description: Rule identifier with the finding
        device_id:
          type: integer
          description: Device with the finding
        risk_type:
          type: string
          description: Type of risk (violation, unused_rule, shadowed_rule)
        severity:
          type: string
          description: Risk severity level
        description:
          type: string
          description: Description of the risk finding