crowdsec/pkg/models/localapi_swagger.yaml

1018 lines
29 KiB
YAML
Raw Normal View History

swagger: '2.0'
info:
version: 1.0.0
title: Swagger CrowdSec
description: CrowdSec local API
contact:
email: contact@crowdsec.net
host: 127.0.0.1
basePath: /v1
securityDefinitions:
JWTAuthorizer:
type: "apiKey"
name: "Authorization: Bearer"
in: "header"
APIKeyAuthorizer:
type: "apiKey"
name: "X-Api-Key"
in: "header"
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
paths:
/decisions/stream:
get:
description: Returns a list of new/expired decisions. Intended for remediation component that need to "stream" decisions
summary: getDecisionsStream
tags:
- Remediation component
operationId: getDecisionsStream
deprecated: false
produces:
- application/json
parameters:
- name: startup
in: query
required: false
type: boolean
description: 'If true, means that the remediation component is starting and a full list must be provided'
- name: scopes
in: query
required: false
type: string
description: 'Comma separated scopes of decisions to fetch'
- name: origins
in: query
required: false
type: string
description: 'Comma separated name of origins. If provided, then only the decisions originating from provided origins would be returned.'
- name: scenarios_containing
in: query
required: false
type: string
description: 'Comma separated words. If provided, only the decisions created by scenarios containing any of the provided word would be returned.'
- name: scenarios_not_containing
in: query
required: false
type: string
description: 'Comma separated words. If provided, only the decisions created by scenarios, not containing any of the provided word would be returned.'
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/DecisionsStreamResponse'
headers: {}
'400':
description: "400 response"
schema:
$ref: "#/definitions/ErrorResponse"
security:
- APIKeyAuthorizer: []
head:
description: Returns a list of new/expired decisions. Intended for remediation component that need to "stream" decisions
summary: GetDecisionsStream
tags:
- Remediation component
operationId: headDecisionsStream
deprecated: false
produces:
- application/json
parameters:
- name: startup
in: query
required: false
type: boolean
description: 'If true, means that the bouncer is starting and a full list must be provided'
responses:
'200':
description: successful operation
headers: {}
'400':
description: "400 response"
security:
- APIKeyAuthorizer: []
/decisions:
get:
description: Returns information about existing decisions
summary: getDecisions
tags:
- Remediation component
operationId: getDecisions
deprecated: false
produces:
- application/json
parameters:
- name: scope
in: query
required: false
type: string
description: scope to which the decision applies (ie. IP/Range/Username/Session/...)
- name: value
in: query
required: false
type: string
description: the value to match for in the specified scope
- name: type
in: query
required: false
type: string
description: type of decision
- name: ip
in: query
required: false
type: string
description: IP to search for (shorthand for scope=ip&value=)
- name: range
in: query
required: false
type: string
description: range to search for (shorthand for scope=range&value=)
- name: contains
in: query
required: false
type: boolean
description: indicate if you're looking for a decision that contains the value, or that is contained within the value
- name: origins
in: query
required: false
type: string
description: 'Comma separated name of origins. If provided, then only the decisions originating from provided origins would be returned.'
- name: scenarios_containing
in: query
required: false
type: string
description: 'Comma separated words. If provided, only the decisions created by scenarios containing any of the provided word would be returned.'
- name: scenarios_not_containing
in: query
required: false
type: string
description: 'Comma separated words. If provided, only the decisions created by scenarios, not containing any of the provided word would be returned.'
responses:
'200':
description: "successful operation"
schema:
$ref: '#/definitions/GetDecisionsResponse'
'400':
description: "400 response"
schema:
$ref: "#/definitions/ErrorResponse"
head:
description: Returns information about existing decisions
summary: GetDecisions
tags:
- Remediation component
operationId: headDecisions
deprecated: false
produces:
- application/json
parameters:
- name: scope
in: query
required: false
type: string
description: scope to which the decision applies (ie. IP/Range/Username/Session/...)
- name: value
in: query
required: false
type: string
description: the value to match for in the specified scope
- name: type
in: query
required: false
type: string
description: type of decision
- name: ip
in: query
required: false
type: string
description: IP to search for (shorthand for scope=ip&value=)
- name: range
in: query
required: false
type: string
description: range to search for (shorthand for scope=range&value=)
- name: contains
in: query
required: false
type: boolean
description: indicate if you're looking for a decision that contains the value, or that is contained within the value
responses:
'200':
description: "successful operation"
'400':
description: "400 response"
security:
- APIKeyAuthorizer: []
delete:
description: Delete decisions(s) for given filters (only from cscli)
summary: deleteDecisions
tags:
- watchers
operationId: deleteDecisions
deprecated: false
produces:
- application/json
parameters:
- name: scope
in: query
required: false
type: string
description: scope to which the decision applies (ie. IP/Range/Username/Session/...)
- name: value
in: query
required: false
type: string
description: the value to match for in the specified scope
- name: type
in: query
required: false
type: string
description: type of decision
- name: ip
in: query
required: false
type: string
description: IP to search for (shorthand for scope=ip&value=)
- name: range
in: query
required: false
type: string
description: range to search for (shorthand for scope=range&value=)
- name: scenario
in: query
required: false
type: string
description: scenario to search
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/DeleteDecisionResponse'
headers: {}
'400':
description: "400 response"
schema:
$ref: "#/definitions/ErrorResponse"
security:
- JWTAuthorizer: []
'/decisions/{decision_id}':
delete:
description: Delete decision for given decision ID (only from cscli)
summary: DeleteDecision
tags:
- watchers
operationId: DeleteDecision
deprecated: false
produces:
- application/json
parameters:
- name: decision_id
in: path
required: true
type: string
description: ''
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/DeleteDecisionResponse'
headers: {}
'404':
description: "404 response"
schema:
$ref: "#/definitions/ErrorResponse"
security:
- JWTAuthorizer: []
/watchers:
post:
description: This method is used when installing crowdsec (cscli->APIL)
summary: RegisterWatcher
tags:
- watchers
operationId: RegisterWatcher
deprecated: false
produces:
- application/json
consumes:
- application/json
parameters:
- name: body
in: body
required: true
description: Information about the watcher to be registered
schema:
$ref: '#/definitions/WatcherRegistrationRequest'
responses:
'201':
description: Watcher Created
headers: {}
'400':
description: "400 response"
schema:
$ref: "#/definitions/ErrorResponse"
/watchers/login:
post:
description: Authenticate current to get session ID
summary: AuthenticateWatcher
tags:
- watchers
operationId: AuthenticateWatcher
deprecated: false
produces:
- application/json
consumes:
- application/json
parameters:
- name: body
in: body
required: true
description: Information about the watcher to be reset
schema:
$ref: '#/definitions/WatcherAuthRequest'
responses:
'200':
description: Login successful
schema:
$ref: '#/definitions/WatcherAuthResponse'
'403':
description: "403 response"
schema:
$ref: "#/definitions/ErrorResponse"
/alerts:
post:
description: Push alerts to API
summary: pushAlerts
tags:
- watchers
operationId: pushAlerts
deprecated: false
produces:
- application/json
consumes:
- application/json
parameters:
- name: body
in: body
required: true
description: Push alerts to the API
schema:
$ref: '#/definitions/AddAlertsRequest'
responses:
'201':
description: Alert(s) created
schema:
$ref: '#/definitions/AddAlertsResponse'
headers: {}
'400':
description: "400 response"
schema:
$ref: "#/definitions/ErrorResponse"
security:
- JWTAuthorizer: []
get:
description: Allows to search for alerts
summary: searchAlerts
tags:
- watchers
operationId: searchAlerts
deprecated: false
produces:
- application/json
parameters:
- name: scope
in: query
required: false
type: string
description: show alerts for this scope
- name: value
in: query
required: false
type: string
description: show alerts for this value (used with scope)
- name: scenario
in: query
required: false
type: string
description: show alerts for this scenario
- name: ip
in: query
required: false
type: string
description: IP to search for (shorthand for scope=ip&value=)
- name: range
in: query
required: false
type: string
description: range to search for (shorthand for scope=range&value=)
- name: since #shouldn't "since" be a golang-duration format ?
in: query
required: false
type: string
format: date-time
description: 'search alerts newer than delay (format must be compatible with time.ParseDuration)'
- name: until #same as for "since"
in: query
description: 'search alerts older than delay (format must be compatible with time.ParseDuration)'
required: false
type: string
format: date-time
- name: simulated
in: query
required: false
type: boolean
description: if set to true, decisions in simulation mode will be returned as well
- name: has_active_decision
in: query
required: false
type: boolean
description: 'only return alerts with decisions not expired yet'
- name: decision_type
in: query
required: false
type: string
description: 'restrict results to alerts with decisions matching given type'
- name: limit
in: query
required: false
type: number
description: 'number of alerts to return'
- name: origin
in: query
required: false
type: string
description: 'restrict results to this origin (ie. lists,CAPI,cscli)'
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/GetAlertsResponse'
headers: {}
'400':
description: "400 response"
schema:
$ref: "#/definitions/ErrorResponse"
security:
- JWTAuthorizer: []
head:
description: Allows to search for alerts
summary: searchAlerts
tags:
- watchers
operationId: headAlerts
deprecated: false
produces:
- application/json
parameters:
- name: scope
in: query
required: false
type: string
description: show alerts for this scope
- name: value
in: query
required: false
type: string
description: show alerts for this value (used with scope)
- name: scenario
in: query
required: false
type: string
description: show alerts for this scenario
- name: ip
in: query
required: false
type: string
description: IP to search for (shorthand for scope=ip&value=)
- name: range
in: query
required: false
type: string
description: range to search for (shorthand for scope=range&value=)
- name: since #shouldn't "since" be a golang-duration format ?
in: query
required: false
type: string
format: date-time
description: 'search alerts newer than delay (format must be compatible with time.ParseDuration)'
- name: until #same as for "since"
in: query
description: 'search alerts older than delay (format must be compatible with time.ParseDuration)'
required: false
type: string
format: date-time
- name: simulated
in: query
required: false
type: boolean
description: if set to true, decisions in simulation mode will be returned as well
- name: has_active_decision
in: query
required: false
type: boolean
description: 'only return alerts with decisions not expired yet'
- name: decision_type
in: query
required: false
type: string
description: 'restrict results to alerts with decisions matching given type'
- name: limit
in: query
required: false
type: number
description: 'number of alerts to return'
- name: origin
in: query
required: false
type: string
description: 'restrict results to this origin (ie. lists,CAPI,cscli)'
responses:
'200':
description: successful operation
headers: {}
'400':
description: "400 response"
security:
- JWTAuthorizer: []
delete:
description: Allows to delete alerts
summary: deleteAlerts
tags:
- watchers
operationId: deleteAlerts
deprecated: false
produces:
- application/json
parameters:
- name: scope
in: query
required: false
type: string
description: delete alerts for this scope
- name: value
in: query
required: false
type: string
description: delete alerts for this value (used with scope)
- name: scenario
in: query
required: false
type: string
description: delete alerts for this scenario
- name: ip
in: query
required: false
type: string
description: delete Alerts with IP (shorthand for scope=ip&value=)
- name: range
in: query
required: false
type: string
description: delete alerts concerned by range (shorthand for scope=range&value=)
- name: since
in: query
required: false
type: string
format: date-time
description: 'delete alerts added after YYYY-mm-DD-HH:MM:SS'
- name: until
in: query
required: false
type: string
format: date-time
description: 'delete alerts added before YYYY-mm-DD-HH:MM:SS'
- name: has_active_decision
in: query
required: false
type: boolean
description: 'delete only alerts with decisions not expired yet'
- name: alert_source
in: query
required: false
type: string
description: delete only alerts with matching source (ie. cscli/crowdsec)
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/DeleteAlertsResponse'
headers: {}
'400':
description: "400 response"
schema:
$ref: "#/definitions/ErrorResponse"
security:
- JWTAuthorizer: []
'/alerts/{alert_id}':
get:
description: Get alert by ID
summary: GetAlertByID
tags:
- watchers
operationId: GetAlertbyID
deprecated: false
produces:
- application/json
parameters:
- name: alert_id
in: path
required: true
type: string
description: ''
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Alert'
headers: {}
'400':
description: "400 response"
schema:
$ref: "#/definitions/ErrorResponse"
security:
- JWTAuthorizer: []
head:
description: Get alert by ID
summary: GetAlertByID
tags:
- watchers
operationId: HeadAlertbyID
deprecated: false
produces:
- application/json
parameters:
- name: alert_id
in: path
required: true
type: string
description: ''
responses:
'200':
description: successful operation
headers: {}
'400':
description: "400 response"
security:
- JWTAuthorizer: []
delete:
description: Delete alert for given alert ID (only from cscli)
summary: DeleteAlert
tags:
- watchers
operationId: DeleteAlert
deprecated: false
produces:
- application/json
parameters:
- name: alert_id
in: path
required: true
type: string
description: ''
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/DeleteAlertsResponse'
headers: {}
'404':
description: "404 response"
schema:
$ref: "#/definitions/ErrorResponse"
security:
- JWTAuthorizer: []
definitions:
WatcherRegistrationRequest:
title: WatcherRegistrationRequest
type: object
properties:
machine_id:
type: string
password:
type: string
format: password
required:
- machine_id
- password
WatcherAuthRequest:
title: WatcherAuthRequest
type: object
properties:
machine_id:
type: string
password:
type: string
format: password
scenarios:
description: the list of scenarios enabled on the watcher
type: array
items:
type: string
required:
- machine_id
- password
WatcherAuthResponse:
title: WatcherAuthResponse
description: the response of a successful authentication
type: object
properties:
code:
type: integer
expire:
type: string
token:
type: string
Alert:
title: Alert
type: object
properties:
id:
description: 'only relevant for GET, ignored in POST requests'
type: integer
readOnly: true
uuid:
description: 'only relevant for LAPI->CAPI, ignored for cscli->LAPI and crowdsec->LAPI'
type: string
readOnly: true
machine_id:
description: 'only relevant for LAPI->CAPI, ignored for cscli->LAPI and crowdsec->LAPI'
type: string
readOnly: true
created_at:
description: 'only relevant for GET, ignored in POST requests'
type: string
readOnly: true
scenario:
type: string
scenario_hash:
type: string
scenario_version:
type: string
message:
description: a human readable message
type: string
events_count:
type: integer
format: int32
start_at:
type: string
stop_at:
type: string
capacity:
type: integer
format: int32
leakspeed:
type: string
simulated:
type: boolean
events:
description: the Meta of the events leading to overflow
type: array
items:
$ref: '#/definitions/Event'
remediation:
type: boolean
decisions:
type: array
items:
$ref: '#/definitions/Decision'
source:
$ref: '#/definitions/Source'
meta:
$ref: '#/definitions/Meta'
labels:
type: array
items:
type: string
required:
- scenario
- scenario_hash
- scenario_version
- message
- events_count
- start_at
- stop_at
- capacity
- leakspeed
- simulated
- events
- source
Source:
title: Source
type: object
properties:
scope:
description: 'the scope of a source : ip,range,username,etc'
type: string
value:
description: 'the value of a source : the ip, the range, the username,etc'
type: string
ip:
description: provided as a convenience when the source is an IP
type: string
range:
description: provided as a convenience when the source is an IP
type: string
as_number:
description: provided as a convenience when the source is an IP
type: string
as_name:
description: provided as a convenience when the source is an IP
type: string
cn:
type: string
latitude:
type: number
format: float
longitude:
type: number
format: float
required:
- scope
- value
Metrics:
title: Metrics
type: object
properties:
apil_version:
description: the local version of crowdsec/apil
type: string
bouncers:
type: array
items:
$ref: '#/definitions/MetricsBouncerInfo'
machines:
type: array
items:
$ref: '#/definitions/MetricsAgentInfo'
required:
- apil_version
- bouncers
- machines
MetricsBouncerInfo:
title: MetricsBouncerInfo
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
type: object
properties:
custom_name:
type: string
description: name of the component
name:
type: string
description: bouncer type (firewall, php ...)
version:
type: string
description: software version
last_pull:
type: string
description: last bouncer pull date
MetricsAgentInfo:
title: MetricsAgentInfo
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
type: object
properties:
name:
type: string
description: name of the component
version:
type: string
description: software version
last_update:
type: string
description: last agent update date
last_push:
type: string
description: last agent push date
Decision:
title: Decision
type: object
properties:
id:
description: (only relevant for GET ops) the unique id
type: integer
readOnly: true
uuid:
description: 'only relevant for LAPI->CAPI, ignored for cscli->LAPI and crowdsec->LAPI'
type: string
readOnly: true
origin:
description: 'the origin of the decision : cscli, crowdsec'
type: string
type:
description: 'the type of decision, might be ''ban'', ''captcha'' or something custom. Ignored when watcher (cscli/crowdsec) is pushing to APIL.'
type: string
scope:
description: 'the scope of decision : does it apply to an IP, a range, a username, etc'
type: string
value:
description: 'the value of the decision scope : an IP, a range, a username, etc'
type: string
duration:
description: 'the duration of the decisions'
type: string
until:
type: string
description: 'the date until the decisions must be active'
scenario:
type: string
simulated:
type: boolean
description: 'true if the decision result from a scenario in simulation mode'
readOnly: true
required:
- origin
- type
- scope
- value
- duration
- scenario
DeleteDecisionResponse:
title: DeleteDecisionResponse
type: object
properties:
nbDeleted:
type: string
description: "number of deleted decisions"
AddAlertsRequest:
title: AddAlertsRequest
type: array
items:
$ref: '#/definitions/Alert'
AddAlertsResponse:
title: AddAlertsResponse
type: array
items:
type: string
description: alert_id
GetAlertsResponse:
title: AlertsResponse
type: array
items:
$ref: '#/definitions/Alert'
DeleteAlertsResponse:
title: DeleteAlertsResponse
type: object
properties:
nbDeleted:
type: string
description: "number of deleted alerts"
DecisionsStreamResponse:
title: DecisionsStreamResponse
type: object
properties:
new:
$ref: '#/definitions/GetDecisionsResponse'
deleted:
$ref: '#/definitions/GetDecisionsResponse'
Event:
title: Event
type: object
properties:
timestamp:
type: string
meta:
$ref: '#/definitions/Meta'
required:
- timestamp
- meta
GetDecisionsResponse:
title: GetDecisionsResponse
type: array
items:
$ref: '#/definitions/Decision'
Meta:
title: Meta
description: the Meta data of the Alert itself
type: array
items:
type: object
properties:
key:
type: string
value:
type: string
ErrorResponse:
type: "object"
required:
- "message"
properties:
message:
type: "string"
description: "Error message"
errors:
type: "string"
description: "more detail on individual errors"
title: "error response"
description: "error response return by the API"
tags:
- name: Remediation component
description: 'Operations about decisions : bans, captcha, rate-limit etc.'
- name: watchers
description: 'Operations about watchers : cscli & crowdsec'
externalDocs:
url: 'https://github.com/crowdsecurity/crowdsec'
description: Find out more about CrowdSec