Censys Platform — Adversary Investigation

naftiko: 1.0.0-alpha2
info:
  label: Censys Platform — Adversary Investigation
  description: 'Censys Platform — Adversary Investigation. 11 operation(s). Lead operation: Censys CensEye: Create a Pivot Analysis Job. Self-contained Naftiko capability covering one Censys business surface.'
  tags:
    - Censys
    - Platform
    - Adversary Investigation
  created: '2026-05-29'
  modified: '2026-05-29'
binds:
  - namespace: env
    keys:
      CENSYS_PERSONAL_ACCESS_TOKEN: CENSYS_PERSONAL_ACCESS_TOKEN
capability:
  consumes:
    - type: http
      namespace: platform-adversary-investigation
      baseUri: https://api.platform.censys.io
      description: Censys Platform — Adversary Investigation business capability. Self-contained, no shared references.
      authentication:
        type: bearer
        token: '{{env.CENSYS_PERSONAL_ACCESS_TOKEN}}'
      resources:
        - name: v3-threat-hunting-censeye-jobs
          path: /v3/threat-hunting/censeye/jobs
          operations:
            - name: v3-threathunting-censeye-jobs-create
              method: POST
              description: "Censys CensEye: Create a Pivot Analysis Job"
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-censeye-jobs-job-id
          path: /v3/threat-hunting/censeye/jobs/{job_id}
          operations:
            - name: v3-threathunting-censeye-jobs-get
              method: GET
              description: "Censys CensEye: Get Job Status"
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: job_id
                  in: path
                  type: string
                  required: true
                  description: The unique identifier of the CensEye job.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-censeye-jobs-job-id-results
          path: /v3/threat-hunting/censeye/jobs/{job_id}/results
          operations:
            - name: v3-threathunting-censeye-job-results
              method: GET
              description: "Censys CensEye: Get Job Results"
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: job_id
                  in: path
                  type: string
                  required: true
                  description: The unique identifier of the CensEye job.
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of results per page (max 100)
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from previous response
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-certificate-certificate-id-observations-hosts
          path: /v3/threat-hunting/certificate/{certificate_id}/observations/hosts
          operations:
            - name: v3-threathunting-get-host-observations-with-certificate
              method: GET
              description: Censys Get Host History for a Certificate
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: certificate_id
                  in: path
                  type: string
                  required: true
                  description: SHA-256 hash of the certificate
                - name: start_time
                  in: query
                  type: string
                  required: false
                  description: Only show ranges ending at or after this time (ISO 8601)
                - name: end_time
                  in: query
                  type: string
                  required: false
                  description: Only show ranges starting at or before this time (ISO 8601)
                - name: port
                  in: query
                  type: integer
                  required: false
                  description: The port to filter by
                - name: protocol
                  in: query
                  type: string
                  required: false
                  description: The transport protocol to filter by
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from previous response to retrieve next page of results
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of results per page. Maximum 100, defaults to 100 if not specified
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-host-ip-observations-endpoints
          path: /v3/threat-hunting/host/{ip}/observations/endpoints
          operations:
            - name: v3-threathunting-endpoint-observations-on-host
              method: GET
              description: Censys Get Endpoint Observation History for a Host
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: start_time
                  in: query
                  type: string
                  required: false
                  description: Start of date range (RFC3339 format, e.g., 2024-01-01T00:00:00Z). If not specified, defaults to the maximum query window back from the end time.
                - name: end_time
                  in: query
                  type: string
                  required: false
                  description: End of date range (RFC3339 format, e.g., 2024-01-31T23:59:59Z). If not specified, defaults to now. Cannot be in the future.
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of results per page (max 100)
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from previous response
                - name: port
                  in: query
                  type: integer
                  required: false
                  description: Filter by port number
                - name: observation_value
                  in: query
                  type: string
                  required: false
                  description: Filter by observation value for the selected observation_type
                - name: ip
                  in: path
                  type: string
                  required: true
                  description: The IP address of a host.
                - name: observation_type
                  in: query
                  type: string
                  required: true
                  description: Endpoint observation type to query.
                - name: order_by
                  in: query
                  type:
                    - array
                    - "null"
                  required: false
                  description: Order observations by these fields. Multiple values can be provided (e.g., ['port DESC', 'observation_value ASC']).
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-host-ip-observations-fingerprints
          path: /v3/threat-hunting/host/{ip}/observations/fingerprints
          operations:
            - name: v3-threathunting-fingerprint-observations-on-host
              method: GET
              description: Censys Get Fingerprint Observation History for a Host
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: start_time
                  in: query
                  type: string
                  required: false
                  description: Start of date range (RFC3339 format, e.g., 2024-01-01T00:00:00Z). If not specified, defaults to the maximum query window back from the end time.
                - name: end_time
                  in: query
                  type: string
                  required: false
                  description: End of date range (RFC3339 format, e.g., 2024-01-31T23:59:59Z). If not specified, defaults to now. Cannot be in the future.
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of results per page (max 100)
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from previous response
                - name: port
                  in: query
                  type: integer
                  required: false
                  description: Filter by port number
                - name: transport_protocol
                  in: query
                  type: string
                  required: false
                  description: Filter by transport protocol when supported by the selected observation_type
                - name: observation_value
                  in: query
                  type: string
                  required: false
                  description: Filter by observation value for the selected observation_type
                - name: ip
                  in: path
                  type: string
                  required: true
                  description: The IP address of a host.
                - name: observation_type
                  in: query
                  type: string
                  required: true
                  description: Fingerprint observation type to query.
                - name: order_by
                  in: query
                  type:
                    - array
                    - "null"
                  required: false
                  description: Order observations by these fields. Multiple values can be provided (e.g., ['port DESC', 'observation_value ASC']). transport_protocol ordering is only supported for observation types whose timelines expose that field; see the endpoint description for details.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-host-ip-observations-threats
          path: /v3/threat-hunting/host/{ip}/observations/threats
          operations:
            - name: v3-threathunting-threats-on-host
              method: GET
              description: Censys Get Threat History for a Host
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: start_time
                  in: query
                  type: string
                  required: false
                  description: Start of date range (RFC3339 format, e.g., 2024-01-01T00:00:00Z). If not specified, defaults to the maximum query window back from the end time.
                - name: end_time
                  in: query
                  type: string
                  required: false
                  description: End of date range (RFC3339 format, e.g., 2024-01-31T23:59:59Z). If not specified, defaults to now. Cannot be in the future.
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of results per page (max 100)
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from previous response
                - name: port
                  in: query
                  type: integer
                  required: false
                  description: Filter by port number
                - name: protocol
                  in: query
                  type: string
                  required: false
                  description: Filter by application protocol
                - name: threat_name
                  in: query
                  type: string
                  required: false
                  description: Filter by threat name
                - name: transport_protocol
                  in: query
                  type: string
                  required: false
                  description: Filter by transport protocol
                - name: ip
                  in: path
                  type: string
                  required: true
                  description: The IP address of a host.
                - name: order_by
                  in: query
                  type:
                    - array
                    - "null"
                  required: false
                  description: Order observations by these fields. Multiple values can be provided to sort by multiple fields (e.g., ['port DESC', 'protocol ASC']).
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-scans-discovery
          path: /v3/threat-hunting/scans/discovery
          operations:
            - name: v3-threathunting-scans-discovery
              method: POST
              description: "Censys Live Discovery: Initiate a New Scan"
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-threats
          path: /v3/threat-hunting/threats
          operations:
            - name: v3-threathunting-threats-list
              method: GET
              description: Censys List Active Threats
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: query
                  in: query
                  type: string
                  required: false
                  description: Optional CenQL filter to constrain threats list
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-value-counts
          path: /v3/threat-hunting/value-counts
          operations:
            - name: v3-threathunting-value-counts
              method: POST
              description: "Censys CensEye: Retrieve Value Counts to Discover Pivots"
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-threat-hunting-web-webproperty-id-observations-threats
          path: /v3/threat-hunting/web/{webproperty_id}/observations/threats
          operations:
            - name: v3-threathunting-threats-on-web
              method: GET
              description: Censys Get Threat History for a Web Property
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  description: "The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter."
                - name: start_time
                  in: query
                  type: string
                  required: false
                  description: Start of date range (RFC3339 format, e.g., 2024-01-01T00:00:00Z). If not specified, defaults to the maximum query window back from the end time.
                - name: end_time
                  in: query
                  type: string
                  required: false
                  description: End of date range (RFC3339 format, e.g., 2024-01-31T23:59:59Z). If not specified, defaults to now. Cannot be in the future.
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of results per page (max 100)
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from previous response
                - name: threat_name
                  in: query
                  type: string
                  required: false
                  description: Filter by threat name
                - name: webproperty_id
                  in: path
                  type: string
                  required: true
                  description: A web property identifier in hostname:port format.
                - name: order_by
                  in: query
                  type:
                    - array
                    - "null"
                  required: false
                  description: Order observations by these fields. Multiple values can be provided to sort by multiple fields (e.g., ['threat_name DESC']).
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
  exposes:
    - type: rest
      namespace: platform-adversary-investigation-rest
      port: 8080
      description: REST adapter for Censys Platform — Adversary Investigation. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/threat-hunting/censeye/jobs
          name: threat-hunting-censeye-jobs
          description: REST surface for threat-hunting-censeye-jobs.
          operations:
            - method: POST
              name: v3-threathunting-censeye-jobs-create
              description: "Censys CensEye: Create a Pivot Analysis Job"
              call: platform-adversary-investigation.v3-threathunting-censeye-jobs-create
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/threat-hunting/censeye/jobs/{job_id}
          name: threat-hunting-censeye-jobs-job-id
          description: REST surface for threat-hunting-censeye-jobs-job-id.
          operations:
            - method: GET
              name: v3-threathunting-censeye-jobs-get
              description: "Censys CensEye: Get Job Status"
              call: platform-adversary-investigation.v3-threathunting-censeye-jobs-get
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                job_id: rest.job_id
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/threat-hunting/censeye/jobs/{job_id}/results
          name: threat-hunting-censeye-jobs-job-id-results
          description: REST surface for threat-hunting-censeye-jobs-job-id-results.
          operations:
            - method: GET
              name: v3-threathunting-censeye-job-results
              description: "Censys CensEye: Get Job Results"
              call: platform-adversary-investigation.v3-threathunting-censeye-job-results
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                job_id: rest.job_id
                page_size: rest.page_size
                page_token: rest.page_token
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/threat-hunting/certificate/{certificate_id}/observations/hosts
          name: threat-hunting-certificate-certificate-id-observations-hosts
          description: REST surface for threat-hunting-certificate-certificate-id-observations-hosts.
          operations:
            - method: GET
              name: v3-threathunting-get-host-observations-with-certificate
              description: Censys Get Host History for a Certificate
              call: platform-adversary-investigation.v3-threathunting-get-host-observations-with-certificate
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                certificate_id: rest.certificate_id
                start_time: rest.start_time
                end_time: rest.end_time
                port: rest.port
                protocol: rest.protocol
                page_token: rest.page_token
                page_size: rest.page_size
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/threat-hunting/host/{ip}/observations/endpoints
          name: threat-hunting-host-ip-observations-endpoints
          description: REST surface for threat-hunting-host-ip-observations-endpoints.
          operations:
            - method: GET
              name: v3-threathunting-endpoint-observations-on-host
              description: Censys Get Endpoint Observation History for a Host
              call: platform-adversary-investigation.v3-threathunting-endpoint-observations-on-host
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                start_time: rest.start_time
                end_time: rest.end_time
                page_size: rest.page_size
                page_token: rest.page_token
                port: rest.port
                observation_value: rest.observation_value
                ip: rest.ip
                observation_type: rest.observation_type
                order_by: rest.order_by
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/threat-hunting/host/{ip}/observations/fingerprints
          name: threat-hunting-host-ip-observations-fingerprints
          description: REST surface for threat-hunting-host-ip-observations-fingerprints.
          operations:
            - method: GET
              name: v3-threathunting-fingerprint-observations-on-host
              description: Censys Get Fingerprint Observation History for a Host
              call: platform-adversary-investigation.v3-threathunting-fingerprint-observations-on-host
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
 

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/censys/refs/heads/main/capabilities/platform-adversary-investigation.yaml