Postman Secret Scanner Bridge

naftiko: "1.0.0-alpha2"

info:
  title: Postman Secret Scanner Bridge
  description: >-
    Bridges Postman's Secret Scanner findings (leaked credentials in
    public collections, public workspaces, etc.) into Naftiko's webhook-
    driven workflows so the Naftiko engine can act on them — alert,
    rotate, escalate, or block the offending capability. Closes the loop
    between "Postman saw a leaked secret" and "Naftiko can do something
    about it."
  tags:
    - Naftiko
    - Postman
    - Partnership
    - Secret-Scanner
    - Security
    - Incident-Response
  created: '2026-05-15'
  modified: '2026-05-15'

binds:
  - namespace: postman-env
    description: Postman API key.
    keys:
      POSTMAN_API_KEY: POSTMAN_API_KEY

capability:
  consumes:
    - namespace: postman
      type: http
      baseUri: https://api.getpostman.com
      authentication:
        type: bearer
        token: '{{POSTMAN_API_KEY}}'
      resources:
        - name: list-secret-findings
          path: '/secret-scanner/findings'
          operations:
            - name: list-secret-findings
              method: GET
              inputParameters:
                - { name: status, in: query, type: string, required: false }
                - { name: since, in: query, type: string, required: false }
                - { name: cursor, in: query, type: string, required: false }
        - name: secret-finding
          path: '/secret-scanner/findings/{{finding_id}}'
          operations:
            - name: get-secret-finding
              method: GET
              inputParameters:
                - { name: finding_id, in: path, required: true }
            - name: resolve-secret-finding
              method: POST
              inputParameters:
                - { name: finding_id, in: path, required: true }
        - name: secret-scanner-summary
          path: '/secret-scanner/summary'
          operations:
            - name: get-secret-scanner-summary
              method: GET

  exposes:
    - type: rest
      address: 0.0.0.0
      port: 8080
      namespace: postman-secret-scanner-bridge-rest
      description: REST surface for managing Postman Secret Scanner findings.
      resources:
        - name: list-secret-findings
          path: '/secret-findings'
          operations:
            - name: list-secret-findings
              method: GET
              inputParameters:
                - { name: status, in: query, type: string, required: false }
                - { name: since, in: query, type: string, required: false }
                - { name: cursor, in: query, type: string, required: false }
              call: postman.list-secret-findings
        - name: secret-finding
          path: '/secret-findings/{finding_id}'
          operations:
            - name: get-secret-finding
              method: GET
              inputParameters:
                - { name: finding_id, in: path, type: string, required: true }
              call: postman.get-secret-finding
            - name: resolve-secret-finding
              method: POST
              inputParameters:
                - { name: finding_id, in: path, type: string, required: true }
              call: postman.resolve-secret-finding
        - name: get-secret-scanner-summary
          path: '/secret-findings/summary'
          operations:
            - name: get-secret-scanner-summary
              method: GET
              call: postman.get-secret-scanner-summary

    - type: mcp
      address: 0.0.0.0
      port: 3010
      namespace: postman-secret-scanner-bridge-mcp
      description: MCP server for security agents to query + resolve Postman Secret Scanner findings.
      tools:
        - name: list-secret-findings
          description: List Postman Secret Scanner findings (optionally filtered by status / since).
          hints: { readOnly: true }
          inputParameters:
            - { name: status, type: string, required: false, description: Filter by status (open / resolved / muted). }
            - { name: since, type: string, required: false, description: ISO 8601 timestamp lower bound. }
            - { name: cursor, type: string, required: false, description: Pagination cursor. }
          call: postman.list-secret-findings
        - name: get-secret-finding
          description: Get a single Postman Secret Scanner finding.
          hints: { readOnly: true }
          inputParameters:
            - { name: finding_id, type: string, required: true, description: Postman Secret Scanner finding ID. }
          call: postman.get-secret-finding
        - name: resolve-secret-finding
          description: Mark a Postman Secret Scanner finding as resolved.
          hints: { destructiveHint: true }
          inputParameters:
            - { name: finding_id, type: string, required: true, description: Postman Secret Scanner finding ID. }
          call: postman.resolve-secret-finding
        - name: get-secret-scanner-summary
          description: Get the aggregate Postman Secret Scanner summary (counts by status / severity).
          hints: { readOnly: true }
          call: postman.get-secret-scanner-summary