yara_openapi.yaml

openapi: "3.0.0"
info:
  version: 0.4.0
  title: Yara REST Server
  description: A Yara REST server
  contact:
    name: David Turland
    email: david@turland.org
    url: https://github.com/DavidTurland/yara-rest
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: http://127.0.0.1:{port}/{basepath}
    description: Yara Localhost REST-Server
    variables:
      port:
        enum:
          - '8080'
        default: '8080'
      basepath:
        default: api
paths:
  /info:
    get:
      description: |
        Requests server info
         - API version
         - OpenAPI version
         - num_threads
      operationId: get_info
      responses:
        '200':
          description: info file response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResult'
  /rules/compile:
    post:
      description: comiles rule files, each with optional namespace
      operationId: rules_compile_post
      requestBody:
        description: variable to be defined
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleFiles'
      responses:
        '200':
          description: OK
        '412':
          description: Unexpected Compiler Error
        '500':
          description: Compiler broken by previous call
  /rules/save:
    put:
      description: Saves compiled rules'
      operationId: rules_save_put
      parameters:
        - name: filename
          in: path
          description: filename to save compiled rules to
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '501':
          description: Not Implemented (yet)
  /rules/load:
    post:
      description: Loads pre-compiled rules'
      operationId: rules_load_post
      parameters:
        - name: filename
          in: path
          description: filename to load compiled rules from
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '501':
          description: Not Implemented (yet)
  /externalvar:
    post:
      description: defines a new external variable
      operationId: externalvar
      requestBody:
        description: variable to be defined
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalVariable'
      responses:
        '200':
          description: OK
        '412':
          description: Rules already extracted, cannot define new external variable
        '500':
          description: Define External broken by previous call
  /scan/file:
    post:
      description: |
          scans a file using a specific scanner
      operationId: scanfile_post
      summary: scan a file using a specific scanner
      requestBody:
        $ref: '#/components/requestBodies/ScanFileBody'
        description: Optional description in *Markdown*
      responses:
        '200':
          description: scan file response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResult'
        '412':
          description: Unexpected Scan Error
  /scan/string:
    post:
      description: |
          scans a string using a specific scanner
      operationId: scanstring_post
      summary: scan a string using a specific scanner
      requestBody:
        $ref: '#/components/requestBodies/ScanStringBody'
        description: Optional description in *Markdown*
      responses:
        '200':
          description: scan string response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResult'
        '412':
          description: Unexpected Scan Error
components:
  requestBodies:
    ScanFileBody:
      description: A JSON object containing a scan file request
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScanFile'
    ScanStringBody:
      description: A JSON object containing a scan string request
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScanString'
  schemas:
    ExternalVariable:
      type: object
      required:
        - component
        - type
        - identifier
        - value
      properties:
        component:
          description: which component to define veriable for
          example: compiler
          type: string
          enum: [compiler,rules,scanner]
        type:
          description: type of external variable to define
          type: string
          example: boolean
          enum: [integer,float,boolean,string]
        identifier:
          type: string
        value:
          type: string
          example: true
        scanner:
          description: scanner to assign ext variable to (required if component isscanner)
          type: integer
          format: int64
          example: 1234  
    RuleFiles:
      type: object
      description: Container of Rule files
      properties:
        rules:
          type: array
          items:
            $ref: '#/components/schemas/RuleFile' 
    RuleFile:
      type: object
      description: Rulefile with optional namespace
      required:
        - filepath
      properties:
        namespace:
          description: optional namespace
          type: string
        filepath:    
          description: filename of rule to compile
          type: string     
    ScanResult:
      type: object
      required:
        - returncode
      properties:
        returncode:
          type: string
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule' 
    InfoResult:
      type: object
      required:
        - returncode
      properties:
        returncode:
          type: string
        meta:
          type: object
          additionalProperties:
            type: string
          example:
            version : '0.3.0'
            num_threads : '20'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    ScanFileRules:
      type: object
      description: scan file request with accompanying rules
      properties:
        filename:
          type: string
          example: /home/davidt/_dev/yara-rest-admin/pay_immediately.txt
        rules:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/Rule'
    ScanFile:
      type: object
      description: scan file request with a scanner( referenced by id)
      properties:
        scannerid:
          description: scanner id to use (default 0)
          type: integer
          format: int32
          default: 0
          example: 0 
        filename:
          type: string
          example: /home/davidt/_dev/yara-rest-admin/pay_immediately.txt
    ScanString:
      type: object
      description: scan string with a scanner( referenced by id)
      required:
        - data
      properties:
        scannerid:
          description: scanner id to use (default 0)
          type: integer
          format: int32
          default: 0
          example: 0 
        data:
          type: string
          example: wibble.com
        length:
          description: |
            length of data. If ommitted then data is assumed to be 
                            a string and length == strlen ( you have been warned)
          type: integer
          format: int32
          example: 10
    Namespace:
      type: object
      properties:
        name:
          type: string
          example: malware.inc
    Meta:
      type: object
      properties:
        name:
          type: string
    Rule:
      type: object
      properties:
        identifier:
          type: string
        tags:
          type: array
          maxItems: 3
          items:
            type: string
        meta:
          type: object
          additionalProperties:
            type: string
          example:
            domain : meta1
            reason : meta2
        strings:
          type: array
          maxItems: 1000
          items:
            type: string
          example:
            - strings1
            - strings2
        namespace:
          type: string
          example:
            - wibblenamespace