HoneyLabs Lists API

openapi: 3.2.0
info:
  title: HoneyLabs Lists API
  version: 1.2.0
  summary: Primary honeypot sensor observations, queryable.
  description: 'HoneyLabs publishes what its own internet-facing honeypot sensors observe. Every record is first-hand.


    **If you are an AI agent, prefer the MCP server** at `https://mcp.honeylabs.net/mcp` (server card: `https://mcp.honeylabs.net/mcp/server-card`). The tools aggregate for you, so one call replaces a client you would otherwise write and maintain.


    **Prefer list endpoints over loops.** `/api/cves` returns every CVE currently being probed in one request; requesting them one id at a time costs far more for both sides and will hit limits quickly.


    Keys are free and issued at once at https://honeylabs.net/dashboard. Plans, prices and limits are in `/pricing.json`; every interface is listed in `/.well-known/api-catalog` (RFC 9727).'
  contact:
    name: HoneyLabs
    url: https://honeylabs.net
  license:
    name: HoneyLabs terms of service
    url: https://honeylabs.net/terms
  termsOfService: https://honeylabs.net/terms
servers:
- url: https://honeylabs.net
security:
- bearerAuth: []
tags:
- name: Lists
  description: Cheaper. Ask for many things at once.
paths:
  /api/cves:
    get:
      tags:
      - Lists
      operationId: listCves
      summary: Every CVE currently observed being probed
      description: Requires a key. This is the endpoint to use instead of looping over /api/cves/{id}. Computed once per cache period; while a first computation is still running the answer is 503 with Retry-After, never an empty list.
      parameters:
      - name: window
        in: query
        schema:
          type: string
          enum:
          - 1h
          - 24h
          - 7d
          - 30d
          - 90d
          default: 7d
        description: Clamped to the plan's maximum. A shortened response carries window_notice.
      responses:
        '200':
          description: CVEs with counts and first/last seen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CveList'
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '429':
          description: Limit reached. The body names a cheaper endpoint for the same question; Retry-After is accurate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '503':
          description: The list is being computed and no earlier copy exists. Retry after the Retry-After seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
  /api/asns:
    get:
      tags:
      - Lists
      operationId: listAsns
      summary: Most active autonomous systems
      responses:
        '200':
          description: ASNs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsnList'
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '429':
          description: Limit reached. The body names a cheaper endpoint for the same question; Retry-After is accurate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
  /api/ports:
    get:
      tags:
      - Lists
      operationId: listPorts
      summary: Most probed ports
      responses:
        '200':
          description: Ports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortList'
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '429':
          description: Limit reached. The body names a cheaper endpoint for the same question; Retry-After is accurate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
  /api/top-actors:
    get:
      tags:
      - Lists
      operationId: listTopActors
      summary: Most active source addresses
      responses:
        '200':
          description: Actors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActorList'
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '429':
          description: Limit reached. The body names a cheaper endpoint for the same question; Retry-After is accurate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
  /api/user-agents:
    get:
      tags:
      - Lists
      operationId: listUserAgents
      summary: Most seen user-agents
      responses:
        '200':
          description: User agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAgentList'
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '429':
          description: Limit reached. The body names a cheaper endpoint for the same question; Retry-After is accurate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
  /api/stats:
    get:
      tags:
      - Lists
      operationId: getStats
      summary: Platform counters
      security: []
      description: Unmetered and needs no key. Event counts (total_events, events_24h, events_1h) are first contact only. Address, network and country counts are distinct over first contact and interactive sessions together.
      responses:
        '200':
          description: Counters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stats'
        '503':
          description: Data backend briefly unavailable. Retry-After is set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '429':
          description: Per-address request rate exceeded. Unmetered does not mean unlimited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
  /feed/{name}.{format}:
    get:
      tags:
      - Lists
      operationId: getPublicFeed
      summary: A curated public feed, no key needed
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          enum:
          - exploiters
          - malware-infrastructure
          - malware-samples
          - second-stage-urls
          - fingerprints
          - credentials
          - about
        example: exploiters
      - name: format
        in: path
        required: true
        schema:
          type: string
          enum:
          - txt
          - csv
          - json
        example: txt
      responses:
        '200':
          description: The feed. txt is one indicator per line.
          content:
            text/plain:
              schema:
                type: string
            text/csv:
              schema:
                type: string
            application/json:
              schema: {}
        '400':
          description: Unknown feed; the body lists the public feeds
  /feed/{token}:
    get:
      tags:
      - Lists
      operationId: getWatchFeed
      summary: A saved watchlist as a blocklist URL
      description: The token comes from the dashboard and works without a login. Append .csv or .json to change the format; the default is one address per line. Limited to 200 fetches an hour per token.
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
        example: your-watchlist-token
      responses:
        '200':
          description: The feed
          content:
            text/plain:
              schema:
                type: string
            text/csv:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  type: object
        '429':
          description: Token fetch limit reached; Retry-After says when
components:
  schemas:
    Stats:
      type: object
    CveList:
      type: object
      properties:
        window:
          type: string
        pro:
          type: boolean
        window_notice:
          $ref: '#/components/schemas/WindowNotice'
        cves:
          type: array
          items:
            type: object
            properties:
              tag_id:
                type: string
              title:
                type: string
                description: The detection signature's title, else the KEV catalogue's vulnerabilityName, else a title HoneyLabs writes for an id the interactive sensors record that neither names. Empty when none applies.
              severity:
                type: string
              actively_exploited:
                type: boolean
                description: On the CISA Known Exploited Vulnerabilities catalogue, or flagged as listed by the CVE's detection signatures. The catalogue is the first source and covers CVEs without a signature.
              events:
                type: integer
                description: 'Probes in the window on both sensor types: first_contact_events plus interactive_requests.'
              unique_ips:
                type: integer
                description: Distinct source addresses over both sensor types. An address both saw counts once, so this is not a sum.
              interaction_sessions:
                type: integer
                description: Sessions on interactive sensors that sent the exploit in the window, on any transport. 0 when none.
              first_contact_events:
                type: integer
                description: Requests matching the CVE's detection signatures.
              first_contact_ips:
                type: integer
                description: Distinct addresses behind first_contact_events.
              interactive_requests:
                type: integer
                description: Requests to the interactive sensors that count as a probe for the CVE, plus one per session whose payload proved it without a counted request. 0 when none.
              interactive_sources:
                type: integer
                description: Distinct addresses behind interactive_requests.
              last_seen:
                type:
                - string
                - 'null'
                description: Date (YYYY-MM-DD, UTC) of the latest probe on either sensor type.
              published:
                type:
                - string
                - 'null'
                description: NVD publication date when cached.
              kev_date_added:
                type:
                - string
                - 'null'
                description: The date CISA added the CVE to the KEV catalogue (YYYY-MM-DD, its dateAdded). null when the catalogue does not list it.
      description: 'Counts cover both sensor types: first contact (requests matching the CVE''s detection signatures) and the requests the interactive sensors answered that count as a probe for the CVE (the sensor''s rule for that CVE was the only one the request matched, on a path first contact''s exclusions accept, or the request or its session carried the exploit). A request that matched several CVE rules counts for none. UDP is left out on both sides. A CVE only the interactive sensors saw is a row like any other; its title, severity and KEV flag come from probe_tags or NVD when either has them, and are empty otherwise.'
    WindowNotice:
      type: object
      description: Present when the requested window exceeded the plan and the response was shortened.
      properties:
        requested_days:
          type: integer
        returned_days:
          type: integer
        reason:
          type: string
        upgrade:
          type: string
          format: uri
    AsnList:
      type: object
      properties:
        asns:
          type: array
          items:
            type: object
    Refusal:
      type: object
      description: Every refusal names what to do instead. Read it before retrying.
      properties:
        error:
          type: string
        detail:
          type: string
        how_to_fix:
          type: string
          example: 'Authorization: Bearer <your-api-key>'
        signup:
          type: string
          format: uri
        docs:
          type: string
          format: uri
        cheaper_route:
          type: object
          properties:
            instead_of:
              type: string
            use:
              type: string
            why:
              type: string
        alternatives:
          type: array
          items:
            type: object
            properties:
              when:
                type: string
              use:
                type: string
              why:
                type: string
    PortList:
      type: object
      properties:
        ports:
          type: array
          items:
            type: object
    ActorList:
      type: object
      properties:
        actors:
          type: array
          items:
            type: object
    UserAgentList:
      type: object
      properties:
        window:
          type: string
        user_agents:
          type: array
          items:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Free key from https://honeylabs.net/dashboard
externalDocs:
  description: Docs with worked examples
  url: https://honeylabs.net/docs