@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/ip-intelligence/ip-threat-intelligence.yaml

@@ -0,0 +1,230 @@
+openapi: 3.1.1
+info:
+  title: IP Threat Intelligence API - VPN, Proxy & Tor Detection with Threat Scoring
+  version: 1.0.0
+  description: Retrieve real-time threat intelligence and security signals for a single IPv4 or IPv6 address. Returns an aggregate `threat_score` (0-100) plus detection flags and provider names for VPNs, proxies (including residential proxies), Tor exit nodes, relays, known attackers, bots, spam sources, and cloud-provider ranges. Use `fields`/`excludes` with dot notation (e.g. `security.threat_score`) to trim the response to only the modules you need. If `ip` is omitted, the API returns threat data for the public IP of the requesting client. Bogon and reserved IP addresses return a `423` error, and malformed IP input returns a `400` error, instead of partial data.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: IP Threat Intelligence API Server
+paths:
+  /ip/security:
+    get:
+      tags:
+        - IP Geolocation APIs
+      summary: Retrieve real-time threat intelligence and security signals for an IPv4 or IPv6 address
+      description: Get a threat score along with VPN, proxy, Tor, relay, bot, spam, known-attacker, and cloud-provider detection flags for an IP address.
+      operationId: ipSecurityLookup
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: Format of the response.
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+        - name: ip
+          in: query
+          required: false
+          description: IPv4 or IPv6 address to check for threat intelligence and security signals. If omitted, the public IP of the requesting client is used.
+          schema:
+            type: string
+        - name: fields
+          in: query
+          required: false
+          description: Comma-separated list of fields to return. Supports dot notation (e.g. `security.threat_score`).
+          schema:
+            type: string
+        - name: excludes
+          in: query
+          required: false
+          description: Comma-separated list of fields to remove from the response. Supports dot notation (e.g. `security.is_tor`). The `ip` field is always included and cannot be excluded.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful threat intelligence response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IpSecurityResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    ip: 8.8.8.8
+                    security:
+                      threat_score: 5
+                      is_tor: false
+                      is_proxy: false
+                      proxy_provider_names: []
+                      proxy_confidence_score: 0
+                      proxy_last_seen: ''
+                      is_residential_proxy: false
+                      is_vpn: false
+                      vpn_provider_names: []
+                      vpn_confidence_score: 0
+                      vpn_last_seen: ''
+                      is_relay: false
+                      relay_provider_name: ''
+                      is_anonymous: false
+                      is_known_attacker: false
+                      is_bot: false
+                      is_spam: false
+                      is_cloud_provider: true
+                      cloud_provider_name: Google LLC
+        '400':
+          description: Bad Request — Invalid or missing IP address
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                invalidIp:
+                  summary: Malformed IP address
+                  value:
+                    message: Provided IP address 'invalid' is not valid
+        '423':
+          description: Locked — Bogon or reserved IP address
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                locked:
+                  summary: Bogon or reserved IP address
+                  value:
+                    message: '''10.0.0.1'' is a bogon IP address.'
+components:
+  securitySchemes:
+    ApiKeyAuthHeader:
+      type: apiKey
+      in: header
+      name: X-apiKey
+      description: Pass your API key via the X-apiKey request header.
+    ApiKeyAuthQuery:
+      type: apiKey
+      in: query
+      name: apiKey
+      description: Pass your API key via the apiKey query parameter.
+  schemas:
+    ErrorResponse:
+      type: object
+      required:
+        - message
+      properties:
+        error:
+          type: string
+          description: Short error category or exception type.
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path that produced the error.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the error occurred (ISO 8601).
+    IpSecurityResponse:
+      type: object
+      description: Threat intelligence result for an IP address.
+      required:
+        - ip
+      properties:
+        ip:
+          type: string
+          description: The IP address used for the lookup (IPv4 or IPv6).
+        security:
+          $ref: '#/components/schemas/Security'
+    Security:
+      type: object
+      description: Threat intelligence and security information for the IP.
+      required:
+        - threat_score
+        - is_tor
+        - is_proxy
+        - proxy_confidence_score
+        - is_residential_proxy
+        - is_vpn
+        - vpn_confidence_score
+        - is_relay
+        - is_anonymous
+        - is_known_attacker
+        - is_bot
+        - is_spam
+        - is_cloud_provider
+      properties:
+        threat_score:
+          type: number
+          description: Aggregate risk score from 0 to 100.
+        is_tor:
+          type: boolean
+          description: true if the IP matches a Tor exit node.
+        is_proxy:
+          type: boolean
+          description: true if the IP is associated with a proxy service.
+        proxy_provider_names:
+          type: array
+          items:
+            type: string
+          description: Detected proxy provider names.
+        proxy_confidence_score:
+          type: number
+          description: Proxy detection confidence from 0 to 100.
+        proxy_last_seen:
+          type: string
+          description: Last observed proxy activity date in YYYY-MM-DD.
+        is_residential_proxy:
+          type: boolean
+          description: true if the IP is linked to a residential proxy network.
+        is_vpn:
+          type: boolean
+          description: true if the IP is associated with a VPN service.
+        vpn_provider_names:
+          type: array
+          items:
+            type: string
+          description: Detected VPN provider names.
+        vpn_confidence_score:
+          type: number
+          description: VPN detection confidence from 0 to 100.
+        vpn_last_seen:
+          type: string
+          description: Last observed VPN activity date in YYYY-MM-DD.
+        is_relay:
+          type: boolean
+          description: true if the IP is associated with a relay network.
+        relay_provider_name:
+          type: string
+          description: Relay provider name.
+        is_anonymous:
+          type: boolean
+          description: true if any anonymity signal is present.
+        is_known_attacker:
+          type: boolean
+          description: true if the IP is flagged for known attacker behavior.
+        is_bot:
+          type: boolean
+          description: true if the IP is associated with bot activity.
+        is_spam:
+          type: boolean
+          description: true if the IP is associated with spam activity.
+        is_cloud_provider:
+          type: boolean
+          description: true if the IP belongs to a cloud provider range.
+        cloud_provider_name:
+          type: string
+          description: Cloud provider name.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []