bitbucket.org/Aishee/synsec@v0.0.0-20210414005726-236fc01a153d/pkg/models/localapi_swagger.yaml (about)

     1  swagger: '2.0'
     2  info:
     3    version: 1.0.0
     4    title: Swagger SynSec
     5    description: SynSec local API
     6    contact:
     7      email: contact@synsec.net
     8  host: 127.0.0.1
     9  basePath: /v1
    10  securityDefinitions:
    11    JWTAuthorizer:
    12      type: "apiKey"
    13      name: "Authorization: Bearer"
    14      in: "header"
    15    APIKeyAuthorizer:
    16      type: "apiKey"
    17      name: "X-Api-Key"
    18      in: "header"
    19  schemes:
    20    - https
    21    - http
    22  consumes:
    23    - application/json
    24  produces:
    25    - application/json
    26  paths:
    27    /decisions/stream:
    28      get:
    29        description: Returns a list of new/expired decisions. Intended for bouncers that need to "stream" decisions
    30        summary: getDecisionsStream
    31        tags:
    32          - bouncers
    33        operationId: getDecisionsStream
    34        deprecated: false
    35        produces:
    36          - application/json
    37        parameters:
    38          - name: startup
    39            in: query
    40            required: false
    41            type: boolean
    42            description: 'If true, means that the bouncers is starting and a full list must be provided'
    43        responses:
    44          '200':
    45            description: successful operation
    46            schema:
    47              $ref: '#/definitions/DecisionsStreamResponse'
    48            headers: {}
    49          '400':
    50            description: "400 response"
    51            schema:
    52              $ref: "#/definitions/ErrorResponse"
    53        security:
    54        - APIKeyAuthorizer: []
    55      head:
    56        description: Returns a list of new/expired decisions. Intended for bouncers that need to "stream" decisions
    57        summary: GetDecisionsStream
    58        tags:
    59          - bouncers
    60        operationId: headDecisionsStream
    61        deprecated: false
    62        produces:
    63          - application/json
    64        parameters:
    65          - name: startup
    66            in: query
    67            required: false
    68            type: boolean
    69            description: 'If true, means that the bouncer is starting and a full list must be provided'
    70        responses:
    71          '200':
    72            description: successful operation
    73            headers: {}
    74          '400':
    75            description: "400 response"
    76        security:
    77        - APIKeyAuthorizer: []
    78    /decisions:
    79      get:
    80        description: Returns information about existing decisions
    81        summary: getDecisions
    82        tags:
    83          - bouncers
    84        operationId: getDecisions
    85        deprecated: false
    86        produces:
    87          - application/json
    88        parameters:
    89          - name: scope
    90            in: query
    91            required: false
    92            type: string
    93            description: scope to which the decision applies (ie. IP/Range/Username/Session/...)
    94          - name: value
    95            in: query
    96            required: false
    97            type: string
    98            description: the value to match for in the specified scope
    99          - name: type
   100            in: query
   101            required: false
   102            type: string
   103            description: type of decision
   104          - name: ip
   105            in: query
   106            required: false
   107            type: string
   108            description: IP to search for (shorthand for scope=ip&value=)
   109          - name: range
   110            in: query
   111            required: false
   112            type: string
   113            description: range to search for (shorthand for scope=range&value=)
   114          - name: contains
   115            in: query
   116            required: false
   117            type: boolean
   118            description: indicate if you're looking for a decision that contains the value, or that is contained within the value
   119        responses:
   120          '200':
   121            description: "successful operation"
   122            schema:
   123              $ref: '#/definitions/GetDecisionsResponse'
   124          '400':
   125            description: "400 response"
   126            schema:
   127              $ref: "#/definitions/ErrorResponse"
   128      head:
   129        description: Returns information about existing decisions
   130        summary: GetDecisions
   131        tags:
   132          - bouncers
   133        operationId: headDecisions
   134        deprecated: false
   135        produces:
   136          - application/json
   137        parameters:
   138          - name: scope
   139            in: query
   140            required: false
   141            type: string
   142            description: scope to which the decision applies (ie. IP/Range/Username/Session/...)
   143          - name: value
   144            in: query
   145            required: false
   146            type: string
   147            description: the value to match for in the specified scope
   148          - name: type
   149            in: query
   150            required: false
   151            type: string
   152            description: type of decision
   153          - name: ip
   154            in: query
   155            required: false
   156            type: string
   157            description: IP to search for (shorthand for scope=ip&value=)
   158          - name: range
   159            in: query
   160            required: false
   161            type: string
   162            description: range to search for (shorthand for scope=range&value=)
   163          - name: contains
   164            in: query
   165            required: false
   166            type: boolean
   167            description: indicate if you're looking for a decision that contains the value, or that is contained within the value
   168        responses:
   169          '200':
   170            description: "successful operation"
   171          '400':
   172            description: "400 response"
   173        security:
   174        - APIKeyAuthorizer: []
   175      delete:
   176        description: Delete decisions(s) for given filters (only from ccscli)
   177        summary: deleteDecisions
   178        tags:
   179          - watchers
   180        operationId: deleteDecisions
   181        deprecated: false
   182        produces:
   183          - application/json
   184        parameters:
   185          - name: scope
   186            in: query
   187            required: false
   188            type: string
   189            description: scope to which the decision applies (ie. IP/Range/Username/Session/...)
   190          - name: value
   191            in: query
   192            required: false
   193            type: string
   194            description: the value to match for in the specified scope
   195          - name: type
   196            in: query
   197            required: false
   198            type: string
   199            description: type of decision
   200          - name: ip
   201            in: query
   202            required: false
   203            type: string
   204            description: IP to search for (shorthand for scope=ip&value=)
   205          - name: range
   206            in: query
   207            required: false
   208            type: string
   209            description: range to search for (shorthand for scope=range&value=)
   210        responses:
   211          '200':
   212            description: successful operation
   213            schema:
   214              $ref: '#/definitions/DeleteDecisionResponse'
   215            headers: {}
   216          '400':
   217            description: "400 response"
   218            schema:
   219              $ref: "#/definitions/ErrorResponse"
   220        security:
   221        - JWTAuthorizer: []
   222    '/decisions/{decision_id}':
   223      delete:
   224        description: Delete decision for given ban ID (only from ccscli)
   225        summary: DeleteDecision
   226        tags:
   227          - watchers
   228        operationId: DeleteDecision
   229        deprecated: false
   230        produces:
   231          - application/json
   232        parameters:
   233          - name: decision_id
   234            in: path
   235            required: true
   236            type: string
   237            description: ''
   238        responses:
   239          '200':
   240            description: successful operation
   241            schema:
   242              $ref: '#/definitions/DeleteDecisionResponse'
   243            headers: {}
   244          '404':
   245            description: "404 response"
   246            schema:
   247              $ref: "#/definitions/ErrorResponse"
   248        security:
   249        - JWTAuthorizer: []
   250    /watchers:
   251      post:
   252        description: This method is used when installing synsec (ccscli->APIL)
   253        summary: RegisterWatcher
   254        tags:
   255          - watchers
   256        operationId: RegisterWatcher
   257        deprecated: false
   258        produces:
   259          - application/json
   260        consumes:
   261          - application/json
   262        parameters:
   263          - name: body
   264            in: body
   265            required: true
   266            description: Information about the watcher to be registered
   267            schema:
   268              $ref: '#/definitions/WatcherRegistrationRequest'
   269        responses:
   270          '201':
   271            description: Watcher Created
   272            headers: {}
   273          '400':
   274            description: "400 response"
   275            schema:
   276              $ref: "#/definitions/ErrorResponse"
   277    /watchers/login:
   278      post:
   279        description: Authenticate current to get session ID
   280        summary: AuthenticateWatcher
   281        tags:
   282          - watchers
   283        operationId: AuthenticateWatcher
   284        deprecated: false
   285        produces:
   286          - application/json
   287        consumes:
   288          - application/json
   289        parameters:
   290          - name: body
   291            in: body
   292            required: true
   293            description: Information about the watcher to be reset
   294            schema:
   295              $ref: '#/definitions/WatcherAuthRequest'
   296        responses:
   297          '200':
   298            description: Login successful
   299            schema:
   300              $ref: '#/definitions/WatcherAuthResponse'
   301          '403':
   302            description: "403 response"
   303            schema:
   304              $ref: "#/definitions/ErrorResponse"
   305    /alerts:
   306      post:
   307        description: Push alerts to API
   308        summary: pushAlerts
   309        tags:
   310          - watchers
   311        operationId: pushAlerts
   312        deprecated: false
   313        produces:
   314          - application/json
   315        consumes:
   316          - application/json
   317        parameters:
   318          - name: body
   319            in: body
   320            required: true
   321            description: Push alerts to the API
   322            schema:
   323              $ref: '#/definitions/AddAlertsRequest'
   324        responses:
   325          '201':
   326            description: Alert(s) created
   327            schema:
   328              $ref: '#/definitions/AddAlertsResponse'
   329            headers: {}
   330          '400':
   331            description: "400 response"
   332            schema:
   333              $ref: "#/definitions/ErrorResponse"
   334        security:
   335        - JWTAuthorizer: []
   336      get:
   337        description: Allows to search for alerts
   338        summary: searchAlerts
   339        tags:
   340          - watchers
   341        operationId: searchAlerts
   342        deprecated: false
   343        produces:
   344          - application/json
   345        parameters:
   346          - name: scope
   347            in: query
   348            required: false
   349            type: string
   350            description: show alerts for this scope
   351          - name: value
   352            in: query
   353            required: false
   354            type: string
   355            description: show alerts for this value (used with scope)
   356          - name: scenario
   357            in: query
   358            required: false
   359            type: string
   360            description: show alerts for this scenario
   361          - name: ip
   362            in: query
   363            required: false
   364            type: string
   365            description: IP to search for (shorthand for scope=ip&value=)
   366          - name: range
   367            in: query
   368            required: false
   369            type: string
   370            description: range to search for (shorthand for scope=range&value=)
   371          - name: since #shouldn't "since" be a golang-duration format ?
   372            in: query
   373            required: false
   374            type: string
   375            format: date-time
   376            description: 'search alerts newer than delay (format must be compatible with time.ParseDuration)'
   377          - name: until #same as for "since"
   378            in: query
   379            description: 'search alerts older than delay (format must be compatible with time.ParseDuration)'
   380            required: false
   381            type: string
   382            format: date-time
   383          - name: simulated
   384            in: query
   385            required: false
   386            type: boolean
   387            description: if set to true, decisions in simulation mode will be returned as well
   388          - name: has_active_decision
   389            in: query
   390            required: false
   391            type: boolean
   392            description: 'only return alerts with decisions not expired yet'    
   393          - name: decision_type
   394            in: query
   395            required: false
   396            type: string
   397            description: 'restrict results to alerts with decisions matching given type'
   398          - name: limit
   399            in: query
   400            required: false
   401            type: number
   402            description: 'number of alerts to return' 
   403        responses:
   404          '200':
   405            description: successful operation
   406            schema:
   407              $ref: '#/definitions/GetAlertsResponse'
   408            headers: {}
   409          '400':
   410            description: "400 response"
   411            schema:
   412              $ref: "#/definitions/ErrorResponse"
   413        security:
   414        - JWTAuthorizer: []
   415      head:
   416        description: Allows to search for alerts
   417        summary: searchAlerts
   418        tags:
   419          - watchers
   420        operationId: headAlerts
   421        deprecated: false
   422        produces:
   423          - application/json
   424        parameters:
   425          - name: scope
   426            in: query
   427            required: false
   428            type: string
   429            description: show alerts for this scope
   430          - name: value
   431            in: query
   432            required: false
   433            type: string
   434            description: show alerts for this value (used with scope)
   435          - name: scenario
   436            in: query
   437            required: false
   438            type: string
   439            description: show alerts for this scenario
   440          - name: ip
   441            in: query
   442            required: false
   443            type: string
   444            description: IP to search for (shorthand for scope=ip&value=)
   445          - name: range
   446            in: query
   447            required: false
   448            type: string
   449            description: range to search for (shorthand for scope=range&value=)
   450          - name: since #shouldn't "since" be a golang-duration format ?
   451            in: query
   452            required: false
   453            type: string
   454            format: date-time
   455            description: 'search alerts newer than delay (format must be compatible with time.ParseDuration)'
   456          - name: until #same as for "since"
   457            in: query
   458            description: 'search alerts older than delay (format must be compatible with time.ParseDuration)'
   459            required: false
   460            type: string
   461            format: date-time
   462          - name: simulated
   463            in: query
   464            required: false
   465            type: boolean
   466            description: if set to true, decisions in simulation mode will be returned as well
   467          - name: has_active_decision
   468            in: query
   469            required: false
   470            type: boolean
   471            description: 'only return alerts with decisions not expired yet'    
   472          - name: decision_type
   473            in: query
   474            required: false
   475            type: string
   476            description: 'restrict results to alerts with decisions matching given type'
   477          - name: limit
   478            in: query
   479            required: false
   480            type: number
   481            description: 'number of alerts to return' 
   482        responses:
   483          '200':
   484            description: successful operation
   485            headers: {}
   486          '400':
   487            description: "400 response"
   488        security:
   489        - JWTAuthorizer: []
   490      delete:
   491        description: Allows to delete alerts
   492        summary: deleteAlerts
   493        tags:
   494          - watchers
   495        operationId: deleteAlerts
   496        deprecated: false
   497        produces:
   498          - application/json
   499        parameters:
   500          - name: scope
   501            in: query
   502            required: false
   503            type: string
   504            description: delete alerts for this scope
   505          - name: value
   506            in: query
   507            required: false
   508            type: string
   509            description: delete alerts for this value (used with scope)
   510          - name: scenario
   511            in: query
   512            required: false
   513            type: string
   514            description: delete alerts for this scenario
   515          - name: ip
   516            in: query
   517            required: false
   518            type: string
   519            description: delete Alerts with IP (shorthand for scope=ip&value=)
   520          - name: range
   521            in: query
   522            required: false
   523            type: string
   524            description: delete alerts concerned by range (shorthand for scope=range&value=)
   525          - name: since
   526            in: query
   527            required: false
   528            type: string
   529            format: date-time
   530            description: 'delete alerts added after YYYY-mm-DD-HH:MM:SS'
   531          - name: until
   532            in: query
   533            required: false
   534            type: string
   535            format: date-time
   536            description: 'delete alerts added before YYYY-mm-DD-HH:MM:SS'
   537          - name: has_active_decision
   538            in: query
   539            required: false
   540            type: boolean
   541            description: 'delete only alerts with decisions not expired yet'
   542          - name: alert_source
   543            in: query
   544            required: false
   545            type: string
   546            description: delete only alerts with matching source (ie. ccscli/synsec)
   547        responses:
   548          '200':
   549            description: successful operation
   550            schema:
   551              $ref: '#/definitions/DeleteAlertsResponse'
   552            headers: {}
   553          '400':
   554            description: "400 response"
   555            schema:
   556              $ref: "#/definitions/ErrorResponse"
   557        security:
   558        - JWTAuthorizer: []
   559    '/alerts/{alert_id}':
   560      get:
   561        description: Get alert by ID
   562        summary: GetAlertByID
   563        tags:
   564          - watchers
   565        operationId: GetAlertbyID
   566        deprecated: false
   567        produces:
   568          - application/json
   569        parameters:
   570          - name: alert_id
   571            in: path
   572            required: true
   573            type: string
   574            description: ''
   575        responses:
   576          '200':
   577            description: successful operation
   578            schema:
   579              $ref: '#/definitions/Alert'
   580            headers: {}
   581          '400':
   582            description: "400 response"
   583            schema:
   584              $ref: "#/definitions/ErrorResponse"
   585        security:
   586        - JWTAuthorizer: []
   587      head:
   588        description: Get alert by ID
   589        summary: GetAlertByID
   590        tags:
   591          - watchers
   592        operationId: HeadAlertbyID
   593        deprecated: false
   594        produces:
   595          - application/json
   596        parameters:
   597          - name: alert_id
   598            in: path
   599            required: true
   600            type: string
   601            description: ''
   602        responses:
   603          '200':
   604            description: successful operation
   605            headers: {}
   606          '400':
   607            description: "400 response"
   608        security:
   609        - JWTAuthorizer: []
   610  definitions:
   611    WatcherRegistrationRequest:
   612      title: WatcherRegistrationRequest
   613      type: object
   614      properties:
   615        machine_id:
   616          type: string
   617        password:
   618          type: string
   619          format: password
   620      required:
   621        - machine_id
   622        - password
   623    WatcherAuthRequest:
   624      title: WatcherAuthRequest
   625      type: object
   626      properties:
   627        machine_id:
   628          type: string
   629        password:
   630          type: string
   631          format: password
   632        scenarios:
   633          description: the list of scenarios enabled on the watcher
   634          type: array
   635          items:
   636            type: string
   637      required:
   638        - machine_id
   639        - password
   640    WatcherAuthResponse:
   641      title: WatcherAuthResponse
   642      description: the response of a successful authentication
   643      type: object
   644      properties:
   645        code:
   646          type: integer
   647        expire:
   648          type: string
   649        token:
   650          type: string
   651    Alert:
   652      title: Alert
   653      type: object
   654      properties:
   655        id:
   656          description: 'only relevant for GET, ignored in POST requests'
   657          type: integer
   658          readOnly: true
   659        machine_id:
   660          description: 'only relevant for APIL->APIC, ignored for ccscli->APIL and synsec->APIL'
   661          type: string
   662          readOnly: true
   663        created_at:
   664          description: 'only relevant for GET, ignored in POST requests'
   665          type: string
   666          readOnly: true
   667        scenario:
   668          type: string
   669        scenario_hash:
   670          type: string
   671        scenario_version:
   672          type: string
   673        message:
   674          description: a human readable message
   675          type: string
   676        events_count:
   677          type: integer
   678          format: int32
   679        start_at:
   680          type: string
   681        stop_at:
   682          type: string
   683        capacity:
   684          type: integer
   685          format: int32
   686        leakspeed:
   687          type: string
   688        simulated:
   689          type: boolean
   690        events:
   691          description: the Meta of the events leading to overflow
   692          type: array
   693          items:
   694            $ref: '#/definitions/Event'
   695        remediation:
   696          type: boolean      
   697        decisions:
   698          type: array
   699          items:
   700            $ref: '#/definitions/Decision'
   701        source:
   702          $ref: '#/definitions/Source'
   703        meta:
   704          $ref: '#/definitions/Meta'
   705        labels:
   706          type: array
   707          items:
   708            type: string
   709      required:
   710        - scenario
   711        - scenario_hash
   712        - scenario_version
   713        - message
   714        - events_count
   715        - start_at
   716        - stop_at
   717        - capacity
   718        - leakspeed
   719        - simulated
   720        - events
   721        - source
   722    Source:
   723      title: Source
   724      type: object
   725      properties:
   726        scope:
   727          description: 'the scope of a source : ip,range,username,etc'
   728          type: string
   729        value:
   730          description: 'the value of a source : the ip, the range, the username,etc'
   731          type: string
   732        ip:
   733          description: provided as a convenience when the source is an IP
   734          type: string
   735        range:
   736          description: provided as a convenience when the source is an IP
   737          type: string
   738        as_number:
   739          description: provided as a convenience when the source is an IP
   740          type: string
   741        as_name:
   742          description: provided as a convenience when the source is an IP
   743          type: string
   744        cn:
   745          type: string
   746        latitude:
   747          type: number
   748          format: float
   749        longitude:
   750          type: number
   751          format: float
   752      required:
   753        - scope
   754        - value
   755    Metrics:
   756      title: Metrics
   757      type: object
   758      properties:
   759        apil_version:
   760          description: the local version of synsec/apil
   761          type: string
   762        bouncers:
   763          type: array
   764          items:
   765              $ref: '#/definitions/MetricsSoftInfo'
   766        machines:
   767          type: array
   768          items:
   769              $ref: '#/definitions/MetricsSoftInfo'
   770      required:
   771        - apil_version
   772        - bouncers
   773        - machines
   774    MetricsSoftInfo:
   775      title: MetricsSoftInfo
   776      description: Software version info (so we can warn users about out-of-date software). The software name and the version are "guessed" from the user-agent
   777      type: object
   778      properties:
   779        name:
   780          type: string
   781          description: name of the component
   782        version:
   783          type: string
   784          description: software version
   785    Decision:
   786      title: Decision
   787      type: object
   788      properties:
   789        id:
   790          description: (only relevant for GET ops) the unique id
   791          type: integer
   792          readOnly: true
   793        origin:
   794          description: 'the origin of the decision : ccscli, synsec'
   795          type: string
   796        type:
   797          description: 'the type of decision, might be ''ban'', ''captcha'' or something custom. Ignored when watcher (ccscli/synsec) is pushing to APIL.'
   798          type: string
   799        scope:
   800          description: 'the scope of decision : does it apply to an IP, a range, a username, etc'
   801          type: string
   802        value:
   803          description: 'the value of the decision scope : an IP, a range, a username, etc'
   804          type: string
   805        duration:
   806          type: string
   807        scenario:
   808          type: string
   809        simulated:
   810          type: boolean
   811          description: 'true if the decision result from a scenario in simulation mode'
   812          readOnly: true
   813      required:
   814        - origin
   815        - type
   816        - scope
   817        - value
   818        - duration
   819        - scenario
   820    DeleteDecisionResponse:
   821      title: DeleteDecisionResponse
   822      type: object
   823      properties:
   824        nbDeleted:
   825          type: string
   826          description: "number of deleted decisions"
   827    AddAlertsRequest:
   828      title: AddAlertsRequest
   829      type: array
   830      items:
   831        $ref: '#/definitions/Alert'
   832    AddAlertsResponse:
   833      title: AddAlertsResponse
   834      type: array
   835      items:
   836        type: string
   837        description: alert_id
   838    GetAlertsResponse:
   839      title: AlertsResponse
   840      type: array
   841      items:
   842        $ref: '#/definitions/Alert'
   843    DeleteAlertsResponse:
   844      title: DeleteAlertsResponse
   845      type: object
   846      properties:
   847        nbDeleted:
   848          type: string
   849          description: "number of deleted alerts"
   850    DecisionsStreamResponse:
   851      title: DecisionsStreamResponse
   852      type: object
   853      properties:
   854        new:
   855          $ref: '#/definitions/GetDecisionsResponse'
   856        deleted:
   857          $ref: '#/definitions/GetDecisionsResponse'
   858    Event:
   859      title: Event
   860      type: object
   861      properties:
   862        timestamp:
   863          type: string
   864        meta:
   865          $ref: '#/definitions/Meta'
   866      required:
   867        - timestamp
   868        - meta
   869    GetDecisionsResponse:
   870      title: GetDecisionsResponse
   871      type: array
   872      items:
   873        $ref: '#/definitions/Decision'
   874    Meta:
   875      title: Meta
   876      description: the Meta data of the Alert itself
   877      type: array
   878      items:
   879        type: object
   880        properties:
   881          key:
   882            type: string
   883          value:
   884            type: string
   885    ErrorResponse:
   886      type: "object"
   887      required:
   888      - "message"
   889      properties:
   890        message:
   891          type: "string"
   892          description: "Error message"
   893        errors:
   894          type: "string"
   895          description: "more detail on individual errors"
   896      title: "error response"
   897      description: "error response return by the API"
   898    AddSignalsRequest:
   899      title: "add signals request"
   900      type: "array"
   901      description: "All signals request model"
   902      items:
   903        $ref: "#/definitions/AddSignalsRequestItem"
   904    AddSignalsRequestItem:
   905      type: "object"
   906      required:
   907      - "message"
   908      - "scenario"
   909      - "scenario_hash"
   910      - "scenario_version"
   911      - "source"
   912      - "start_at"
   913      - "stop_at"
   914      properties:
   915        scenario_hash:
   916          type: "string"
   917        scenario:
   918          type: "string"
   919        created_at:
   920          type: "string"
   921        machine_id:
   922          type: "string"
   923        source:
   924          $ref: "#/definitions/Source"
   925        scenario_version:
   926          type: "string"
   927        message:
   928          type: "string"
   929          description: "a human readable message"
   930        start_at:
   931          type: "string"
   932        stop_at:
   933          type: "string"
   934      title: "Signal"
   935  tags:
   936    - name: bouncers
   937      description: 'Operations about decisions : bans, captcha, rate-limit etc.'
   938    - name: watchers
   939      description: 'Operations about watchers : ccscli & synsec'
   940  externalDocs:
   941    url: 'https://bitbucket.org/Aishee/synsec'
   942    description: Find out more about SynSec