openapi: 3.0.0 info: version: 0.0.1 title: Elmasy API description: Documentation for Elmasy API. servers: - url: https://scan.elmasy.com/api - url: http://localhost:8080/api - url: https://dev.elmasy.com/api tags: - name: Basic description: Basic API. - name: Random description: Return random things. - name: Protocol description: Protocol implementations. - name: Scan description: Scanner. paths: /ip: get: summary: Your public IP address. description: Returns your public IP address. tags: - Basic responses: 200: description: Success content: "*/*": schema: type: string application/json: schema: $ref: "#/components/schemas/ResultStr" /random/ip/: get: summary: Get a random public IP address. description: Returns a random public IP address. tags: - Random parameters: - name: version description: The version of the IP protocol. Valid versions are `ipv4`/`4` or `ipv6`/`6`. If `version` is omitted, the return IP version is random. in: query required: false schema: type: string responses: 200: description: Success content: application/json: schema: $ref: "#/components/schemas/ResultStr" 400: description: Invalid IP protocol version. content: application/json: schema: $ref: "#/components/schemas/Error" /random/port: get: summary: Get a random port number. description: Returns a random port. tags: - Random responses: 200: description: Success content: application/json: schema: $ref: "#/components/schemas/ResultStr" "*/*": schema: type: string /protocol/dns/{type}/{name}: get: summary: DNS Lookup. description: > Do a DNS lookup. tags: - Protocol parameters: - name: type description: The question type. Can be `A`, `AAAA`, `MX` or `TXT`. in: path required: true schema: type: string - name: name description: The domain name. in: path required: true schema: type: string responses: 200: description: Successful query. content: application/json: schema: $ref: "#/components/schemas/ResultStrs" 400: description: Invalid type or domain. content: application/json: schema: $ref: "#/components/schemas/Error" 404: description: The domain name not exist (`NXDOMAIN`). content: application/json: schema: $ref: "#/components/schemas/Error" 500: description: > Query or server error. DNS Response codes returned: `FORMERR`, `SERVFAIL`, `NOTIMP`, `REFUSED`, `YXDOMAIN`, `XRRSET`, `NOTAUTH` and `NOTZONE`. Can be other unknown server error. content: application/json: schema: $ref: "#/components/schemas/Error" /protocol/tls: get: summary: Analyze SSL/TLS. description: > A **low level** API to analyze SSL/TLS on ip:port. Returns the supported ciphers. tags: - Protocol parameters: - name: version description: Specify the SSL/TLS version. Can be `ssl30`, `tls10`, `tls11`, `tls12` or `tls13`. in: query required: true schema: type: string - name: network description: Target network. Can be `tcp` or `udp`. Defaults to `tcp`. in: query required: false schema: type: string - name: ip description: The target IP address. in: query required: true schema: type: string - name: port description: The target port. in: query required: true schema: type: string - name: servername description: The server name for SNI. If omitted, SNI is not added to ServerHello. in: query required: false schema: type: string responses: 200: description: Success. content: application/json: schema: type: array items: $ref: "#/components/schemas/TLSVersion" 400: description: Bad request content: application/json: schema: $ref: "#/components/schemas/Error" 500: description: An error occured while scanning. content: application/json: schema: $ref: "#/components/schemas/Error" /protocol/tls/certificate: get: summary: Parse TLS certificate. description: > A **Low Level** API parse a TLS certificate. tags: - Protocol parameters: - name: network description: Target network. Can be `tcp` or `udp`. Defaults to `tcp`. in: query required: false schema: type: string - name: ip description: The target IP address. in: query required: true schema: type: string - name: port description: The target port. in: query required: true schema: type: string - name: servername description: The server name for SNI. in: query required: false schema: type: string responses: 200: description: Success. content: application/json: schema: $ref: "#/components/schemas/Cert" 400: description: Bad Request. content: application/json: schema: $ref: "#/components/schemas/Error" 500: description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/Error" /protocol/probe: get: summary: Probe protocol. description: > A **Low Level** API to probe whether the given protocol is supported on network on ip:port. tags: - Protocol parameters: - name: protocol description: > Protocol to probe. Currently supported: `dns`, `ssl30`, `tls10`, `tls11`, `tls12`, `tls13` and `tls`. If `tls` selected, every versions will be probed and report if any version is supported. in: query required: true schema: type: string - name: network description: Target network. Can be `tcp` or `udp`. Defaults to `tcp`. in: query required: false schema: type: string - name: ip description: The target IP address. in: query required: true schema: type: string - name: port description: The target port. in: query required: true schema: type: string responses: 200: description: Success. content: application/json: schema: $ref: "#/components/schemas/ResultBool" 400: description: Bad request. content: application/json: schema: $ref: "#/components/schemas/Error" 500: description: An error occured while scanning. content: application/json: schema: $ref: "#/components/schemas/Error" /scan: get: summary: Scan target. description: > Scan the given target. Currently, only IPv4 targets are supported. tags: - Scan parameters: - name: target description: Target hostname or IP. in: query required: true schema: type: string - name: port description: The target port. Defaults to `443`. in: query required: false schema: type: string - name: network description: The target network. Can be `tcp` or `udp`, defaults to `tcp`. in: query required: false schema: type: string responses: 200: description: Success. This not means, that no error occured while scanning! These errors are returned in `errors` array. content: application/json: schema: $ref: "#components/schemas/Result" 400: description: Invalid target or port. content: application/json: schema: $ref: "#/components/schemas/Error" 404: description: Target domain not found. content: application/json: schema: $ref: "#/components/schemas/Error" 500: description: Internal error. content: application/json: schema: $ref: "#/components/schemas/Error" /scan/port: get: summary: Port scan description: Port scanner API. tags: - Scan parameters: - name: technique description: The portscan technique. Can be `syn`/`stealth`, `connect` or `udp`. If omitted, `connect` is used. in: query required: false schema: type: string - name: ip description: The target IP address. in: query required: true schema: type: string - name: port description: The target port number. in: query required: true schema: type: string - name: timeout description: Scan timeout in second. Default to 2 seconds. in: query required: false schema: type: string responses: 200: description: > Success. This not mean that the port is open! The possible results are: `open`, `closed` or `filtered` content: application/json: schema: $ref: "#/components/schemas/ResultStr" 400: description: Invalid or missing query parameter. content: application/json: schema: $ref: "#/components/schemas/Error" 403: description: The address is blacklisted. Not scanning! content: application/json: schema: $ref: "#/components/schemas/Error" 500: description: Error. content: application/json: schema: $ref: "#/components/schemas/Error" components: schemas: ResultStr: type: object properties: result: type: string ResultBool: type: object properties: result: type: boolean ResultStrs: type: object properties: results: type: array items: type: string Error: type: object properties: error: type: string Errors: type: object properties: errors: type: array items: type: string Cipher: type: object properties: name: type: string security: type: string PubKey: type: object properties: algo: type: string size: type: integer key: type: string exponent: type: integer modulus: type: string Additional: type: object properties: commonName: type: string hash: type: string notAfter: type: string issuer: type: string publicKey: $ref: "#/components/schemas/PubKey" signatureAlgorithm: type: string Cert: type: object properties: commonName: type: string hash: type: string alternativeNames: type: array items: type: string signatureAlgorithm: type: string publicKey: $ref: "#/components/schemas/PubKey" serialNumber: type: string issuer: type: string notBefore: type: string notAfter: type: string verified: type: boolean verifiedError: type: string chain: type: array items: $ref: "#/components/schemas/Additional" TLSVersion: type: object properties: version: type: string supported: type: boolean ciphers: type: array items: type: object properties: name: type: string security: type: string TLS: type: object properties: versions: type: array items: $ref: "#/components/schemas/TLSVersion" cert: $ref: "#/components/schemas/Cert" Target: type: object properties: ip: type: string tls: $ref: "#/components/schemas/TLS" Result: type: object properties: domain: type: string targets: type: array items: $ref: "#/components/schemas/Target" errors: type: array items: type: string