Demisto Evidence API
The Evidence API from Demisto — 3 operation(s) for evidence.
OpenAPI Specification
swagger: '2.0'
info:
description: 'This is the public REST API to integrate with the demisto server.
HTTP request can be sent using any HTTP-client.
For an example dedicated client take a look at: https://github.com/demisto/demisto-py.
Requests must include API-key that can be generated in the Demisto web client under ''Settings'' -> ''Integrations'' -> ''API keys''
Optimistic Locking and Versioning\:
When using Demisto REST API, you will need to make sure to work on the latest version of the item (incident, entry, etc.), otherwise, you will get a DB version error (which not allow you to override a newer item).
In addition, you can pass ''version\: -1'' to force data override (make sure that other users data might be lost).
Assume that Alice and Bob both read the same data from Demisto server, then they both changed the data, and then both tried to write the new versions back to the server. Whose changes should be saved? Alice’s? Bob’s?
To solve this, each data item in Demisto has a numeric incremental version.
If Alice saved an item with version 4 and Bob trying to save the same item with version 3, Demisto will rollback Bob request and returns a DB version conflict error.
Bob will need to get the latest item and work on it so Alice work will not get lost.
Example request using ''curl''\:
```
curl ''https://hostname:443/incidents/search'' -H ''content-type: application/json'' -H ''accept: application/json'' -H ''Authorization: <API Key goes here>'' --data-binary ''{"filter":{"query":"-status:closed -category:job","period":{"by":"day","fromValue":7}}}'' --compressed
```'
title: Demisto Apikeys Evidence API
version: 2.0.0
host: hostname:443
schemes:
- https
consumes:
- application/json
- application/xml
produces:
- application/json
security:
- api_key: []
- csrf_token: []
- x-xdr-auth-id: []
tags:
- name: Evidence
paths:
/evidence:
post:
description: 'Save an evidence entity
To update evidence custom fields you should lowercase them and remove all spaces. For example: Scan IP -> scanip'
summary: Save evidence
operationId: saveEvidence
parameters:
- name: Evidence
in: body
schema:
$ref: '#/definitions/Evidence'
responses:
'200':
description: The new / updated Evidence
schema:
$ref: '#/definitions/Evidence'
tags:
- Evidence
/evidence/delete:
post:
description: Delete an evidence entity
summary: delete evidence
operationId: deleteEvidenceOp
parameters:
- name: deleteEvidence id
in: body
schema:
$ref: '#/definitions/deleteEvidence'
responses:
'200':
description: Deleted evidence ID
tags:
- Evidence
/evidence/search:
post:
description: Search for an evidence entutiy by filter
summary: Search evidence
operationId: searchEvidence
parameters:
- name: evidencesFilterWrapper
in: body
schema:
$ref: '#/definitions/evidencesFilterWrapper'
responses:
'200':
description: EvidencesSearchResponse
schema:
$ref: '#/definitions/EvidencesSearchResponse'
tags:
- Evidence
definitions:
Period:
type: object
title: Period holds the 'Period' query, such as last 3 days, last 6 hours, between 6 days from now until 3 days from now.
properties:
by:
description: By is used for legacty, and if exists it will override ByTo and ByFrom
type: string
x-go-name: By
byFrom:
type: string
x-go-name: ByFrom
byTo:
type: string
x-go-name: ByTo
field:
type: string
x-go-name: Field
fromValue:
type: string
format: duration
x-go-name: FromValue
toValue:
type: string
format: duration
x-go-name: ToValue
x-go-package: github.com/demisto/server/domain
Duration:
description: 'A Duration represents the elapsed time between two instants
as an int64 nanosecond count. The representation limits the
largest representable duration to approximately 290 years.'
type: integer
format: int64
x-go-package: time
deleteEvidence:
type: object
properties:
evidenceID:
type: string
x-go-name: EvidenceID
x-go-package: github.com/demisto/server/web
Order:
description: Order struct holds a sort field and the direction of sorting
type: object
properties:
asc:
type: boolean
x-go-name: Asc
field:
type: string
x-go-name: Field
fieldType:
type: string
x-go-name: FieldType
x-go-package: github.com/demisto/server/domain
GenericStringDateFilter:
description: GenericStringDateFilter is a general filter that will fetch entities using the Query value and a date filter
type: object
properties:
Cache:
description: Cache of join functions
type: object
additionalProperties:
type: array
items:
type: string
fromDate:
type: string
format: date-time
x-go-name: FromDate
fromDateLicense:
type: string
format: date-time
x-go-name: FromDateLicenseVal
page:
description: 0-based page
type: integer
format: int64
x-go-name: Page
period:
$ref: '#/definitions/Period'
query:
type: string
x-go-name: Query
searchAfter:
description: Efficient next page, pass max sort value from previous page
type: array
items:
type: string
x-go-name: SearchAfter
searchBefore:
description: Efficient prev page, pass min sort value from next page
type: array
items:
type: string
x-go-name: SearchBefore
size:
description: Size is limited to 1000, if not passed it defaults to 0, and no results will return
type: integer
format: int64
x-go-name: Size
sort:
description: The sort order
type: array
items:
$ref: '#/definitions/Order'
x-go-name: Sort
timeFrame:
$ref: '#/definitions/Duration'
toDate:
type: string
format: date-time
x-go-name: ToDate
x-go-package: github.com/demisto/server/repo/entities
EvidencesSearchResponse:
description: EvidencesSearchResponse returns the response from the evidences search
type: object
properties:
evidences:
$ref: '#/definitions/Evidences'
total:
type: integer
format: int64
x-go-name: Total
x-go-package: github.com/demisto/server/repo/entities
Evidence:
type: object
title: Evidence details.
properties:
ShardID:
type: integer
format: int64
description:
description: The description for the resolve
type: string
x-go-name: Description
entryId:
description: The entry ID
type: string
x-go-name: EntryID
fetched:
description: when the evidence entry was fetched
type: string
format: date-time
x-go-name: Fetched
hasRole:
description: Internal field to make queries on role faster
type: boolean
x-go-name: HasRole
id:
type: string
x-go-name: ID
incidentId:
description: The incident ID
type: string
x-go-name: IncidentID
markedBy:
description: the user that marked this evidence
type: string
x-go-name: MarkedBy
markedDate:
description: when this evidence was marked
type: string
format: date-time
x-go-name: MarkedDate
modified:
type: string
format: date-time
x-go-name: Modified
occurred:
description: When this evidence has occurred
type: string
format: date-time
x-go-name: Occurred
previousRoles:
description: PreviousRoleName - do not change this field manually
type: array
items:
type: string
x-go-name: PreviousRoleName
roles:
description: The role assigned to this investigation
type: array
items:
type: string
x-go-name: RoleName
sortValues:
type: array
items:
type: string
x-go-name: SortValues
tags:
description: Tags
type: array
items:
type: string
x-go-name: Tags
tagsRaw:
description: TagsRaw
type: array
items:
type: string
x-go-name: TagsRaw
taskId:
description: when the evidence entry was fetched
type: string
x-go-name: TaskID
version:
type: integer
format: int64
x-go-name: Versn
additionalProperties:
type: object
x-go-package: github.com/demisto/server/domain
Evidences:
description: Evidences is a list of evidence entities
type: array
items:
$ref: '#/definitions/Evidence'
x-go-package: github.com/demisto/server/domain
evidencesFilterWrapper:
type: object
properties:
filter:
$ref: '#/definitions/GenericStringDateFilter'
incidentID:
type: string
x-go-name: IncidentID
x-go-package: github.com/demisto/server/web
securityDefinitions:
api_key:
type: apiKey
name: Authorization
in: header
csrf_token:
type: apiKey
name: X-XSRF-TOKEN
in: header
x-xdr-auth-id:
type: apiKey
name: x-xdr-auth-id
in: header