Skip to content

API

Jump to bottom
Alex Kornitzer edited this page Mar 15, 2018 · 4 revisions

Introduction

API Version 1.0, at time of writing.

This page aims to provide a summary of the API provided by Snake, along with examples.

Command Routes

These routes are used to handle the execution and retrieval of commands provided by the Scale's Commands component. There are two command routes: one for handling single commands and the other for multiple.

Supported Methods

/command
get, post

/commands
get, post

Command

GET

The GET for a command will return a single command for a given file (hash), scale and command.

  • (Required): sha256_digest
    • hash for a sample in Snake
  • (Required): scale
    • scale providing the command
  • (Required): command
    • command to execute
  • (Optional): format
    • default: json
    • the format of the output field, supported types are command dependent
curl 'http://127.0.0.1/command?sha256_digest=df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755&scale=hashes&command=all'

POST

The POST for a command will queue a command for execution for a given file (hash), scale, and command.

  • (Required): sha256_digest
    • hash for a sample in Snake
  • (Required): scale
    • scale providing the command
  • (Required): command
    • command to execute
  • (Optional): args
    • default: none
    • additional arguments provided by a command, these can be required or optional. See Scale Routes
  • (Optional): asynchronous
    • default: false
    • queue the command in the background or wait for result
  • (Optional): format
    • default: json
    • the format of the output field, supported types are command dependent
  • (Optional): timeout
    • default: 600
    • the maximum amount of time a command is allowed to execute for
curl 'http://127.0.0.1/command?sha256_digest=df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755&scale=hashes&command=all' -XPOST

Commands

GET

The GET for commands is more flexible than its singular counterpart, but with flexibility comes additional complexity.

  • (Optional): sha256_digest
    • default: none
    • hash for a sample in Snake
  • (Optional): scale
    • default: none
    • scale providing the command
  • (Optional): command
    • default: none
    • command to execute
  • (Optional): format
    • default: json
    • the format of the output field, supported types are command dependent
curl 'http://127.0.0.1/commands'
curl 'http://127.0.0.1/commands?sha256_digest=df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755'
curl 'http://127.0.0.1/commands?sha256_digest=df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755&scale=hashes'
curl 'http://127.0.0.1/commands?sha256_digest=df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755&scale=hashes&command=all'
curl 'http://127.0.0.1/commands?scale=hashes'
curl 'http://127.0.0.1/commands?command=all'

POST

The POST for commands as with its GET is flexible and complex. For obvious reasons all commands are asynchronous. The main difference between this and its singular counterpart is that a list of commands is expected.

  • (Required): sha256_digests
    • hashes for samples in Snake
  • (Required): scale
    • scale providing the command
  • (Required): command
    • command to execute
  • (Optional): args
    • default: none
    • additional arguments provided by a command, these can be required or optional. See Scale Routes
  • (Optional): asynchronous
    • default: false
    • queue the command in the background or wait for result
  • (Optional): format
    • default: json
    • the format of the output field, supported types are command dependent
    • NOTE: Not used!
  • (Optional): timeout
    • default: 600
    • the maximum amount of time a command is allowed to execute for
curl 'http://127.0.0.1:5000/commands' -d '[
  {"command":"all_strings", "scale": "strings", "sha256_digests":["df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755"]}
]' -H 'Content-Type: application/json' -XPOST

curl 'http://127.0.0.1:5000/commands' -d '[
  {"command":"all_strings", "scale": "strings", "sha256_digests":["all:file"]}
]' -H 'Content-Type: application/json' -XPOST

curl 'http://127.0.0.1:5000/commands' -d '[
  {"command":"all_strings", "scale": "strings", "sha256_digests":["all"]}
]' -H 'Content-Type: application/json' -XPOST

Download Route

This route is used to download a file from Snake.

Supported Methods

/download/<sha256_digest>
get

Download

GET

The GET for download will return the sample for the given hash. Its name will be the filename with .inactive appended.

curl 'http://127.0.0.1/download/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755'

File Routes

These routes are used to handle the manipulation and retrieval of file metadata along with file deletion.

Supported Methods

/file/<sha256_digest>
delete, get, patch, put

/file/<sha256_digest>/hex
get

/files
get

File

This route is used to access, modify and remove the metadata (removal will remove the file on disk).

DELETE

The DELETE for a file will remove the file from disk along with its metadata.

curl 'http://127.0.0.1/file/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -XDELETE

GET

The GET for a file will retrieve the metadata for a given file (hash).

curl 'http://127.0.0.1/file/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755'

PATCH

The PATCH for a file will allow the updating of the description, name, and/or tags fields.

  • (Optional): description
    • default: no change
    • description for a file in Snake
  • (Optional): name
    • default: no change
    • name for a file in Snake
  • (Optional): tags
    • default: no change
    • tags for a file in Snake
curl 'http://127.0.0.1/file/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -d '{
  "description": "the ls binary",
  "name": "ls",
  "tags": "arch, non-malicious"
}' -XPATCH

curl 'http://127.0.0.1/file/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -d '{
  "description": "the ls binary - or is it?"
}' -XPATCH

PUT

The PUT for a file will allow the updating/resetting of the description, name, and/or tags fields. This is pseudo PUT as it will only display put behaviour on the above fields.

  • (Optional): description
    • default: ''
    • description for a file in Snake
  • (Optional): name
    • default: ''
    • name for a file in Snake
  • (Optional): tags
    • default: ''
    • tags for a file in Snake
curl 'http://127.0.0.1/file/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -d '{
  "description": "the ls binary",
  "name": "ls",
  "tags": "arch, non-malicious"
}' -XPUT

curl 'http://127.0.0.1/file/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -d '{
  "description": "the ls binary - or is it?"
}' -XPUT

File Hex

This route is used to hex output of a file.

GET

The GET for a hex file will retrieve a traditional hexdump on the file in question, for now it only returns 16 lines.

curl 'http://127.0.0.1/file/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755/hex'

Files

This route is used to access metadata for multiple files.

GET

The GET for files will allow retrieval of multiple files from Snake's database.

  • (Optional): filter[FIELD]
    • default: none
    • key value pairs used to filter the documents returned
  • (Optional): limit
    • default: none
    • limits the number of documents returned
  • (Optional): operator
    • default: and
    • operator to apply to sort filters
  • (Operational): order
    • default: -1 (descending)
    • order to return the documents in
  • (Operational): sort
    • default: none
    • field to sort documents on
curl 'http://127.0.0.1/files'
curl 'http://127.0.0.1/files?limit=10'
curl 'http://127.0.0.1/files?order=1'
curl 'http://127.0.0.1/files?filter[name]=ls&filter[tags]=tagstagstags'

Memory Routes

These routes are used to handle the manipulation and retrieval of memory metadata along with memory deletion.

Supported Methods

/memory/<sha256_digest>
delete, get, patch, put

/memories
get

Memory

This route is used to access, modify and remove the metadata (removal will remove the memory on disk).

DELETE

The DELETE for a memory will remove the memory from disk along with its metadata.

curl 'http://127.0.0.1/memory/509ff0dfba1798794948c303f5ef37401625c737f750e46773b93e5c77721ef0' -XDELETE

GET

The GET for a memory will retrieve the metadata for a given memory (hash).

curl 'http://127.0.0.1/memory/509ff0dfba1798794948c303f5ef37401625c737f750e46773b93e5c77721ef0'

PATCH

The PATCH for a memory will allow the updating of the description, name, and/or tags fields.

  • (Optional): description
    • default: no change
    • description for a memory in Snake
  • (Optional): name
    • default: no change
    • name for a memory in Snake
  • (Optional): tags
    • default: no change
    • tags for a memory in Snake
curl 'http://127.0.0.1/memory/509ff0dfba1798794948c303f5ef37401625c737f750e46773b93e5c77721ef0' -d '{
  "description": "a process dump in MDMP format",
  "name": "process.dmp",
  "tags": "reverseme"
}' -XPATCH

curl 'http://127.0.0.1/memory/509ff0dfba1798794948c303f5ef37401625c737f750e46773b93e5c77721ef0' -d '{
  "description": "cannot remember what process this is for!"
}' -XPATCH

PUT

The PUT for a memory will allow the updating/resetting of the description, name, and/or tags fields. This is pseudo PUT as it will only display put behaviour on the above fields.

  • (Optional): description
    • default: ''
    • description for a memory in Snake
  • (Optional): name
    • default: ''
    • name for a memory in Snake
  • (Optional): tags
    • default: ''
    • tags for a memory in Snake
curl 'http://127.0.0.1/memory/509ff0dfba1798794948c303f5ef37401625c737f750e46773b93e5c77721ef0' -d '{
  "description": "a process dump in MDMP format",
  "name": "process.dmp",
  "tags": "reverseme"
}' -XPUT

curl 'http://127.0.0.1/memory/509ff0dfba1798794948c303f5ef37401625c737f750e46773b93e5c77721ef0' -d '{
  "description": "cannot remember what process this is for!"
}' -XPUT

Memories

This route is used to access metadata for multiple memories.

GET

The GET for memories will allow retrieval of multiple memories from Snake's database.

  • (Optional): filter[FIELD]
    • default: none
    • key value pairs used to filter the documents returned
  • (Optional): limit
    • default: none
    • limits the number of documents returned
  • (Optional): operator
    • default: and
    • operator to apply to sort filters
  • (Operational): order
    • default: -1 (descending)
    • order to return the documents in
  • (Operational): sort
    • default: none
    • field to sort documents on
curl 'http://127.0.0.1/memories'
curl 'http://127.0.0.1/memories?limit=10'
curl 'http://127.0.0.1/memories?order=1'
curl 'http://127.0.0.1/memories?filter[name]=procdump&filter[tags]=tagstagstags'

Note Routes

These routes are used to retrieve, modify and remove notes related to samples.

Supported Methods

/note/<sha256_digest>
delete, get, patch, put

/note
post

/notes
get, post

Note

This route is used to access, modify and remove the note for a sample.

DELETE

The DELETE for a note will remove the note for a given sample (hash)

curl 'http://127.0.0.1/note/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -XDELETE

GET

The GET for a note will retrieve the note for a given sample (hash).

curl 'http://127.0.0.1/note/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755'

PATCH

The PATCH for a note will allow the updating of the note's body

  • (Optional): body
    • default: no change
    • note for a sample in Snake
curl 'http://127.0.0.1/note/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -d '{
  "body": "I am a cool markdown note"
}' -XPATCH

POST

The POST for a note will create a note for a given sample.

  • (Required): sha256_digest
    • the hash of the sample to create the note for
  • (Required): body
    • note for a sample in Snake
curl 'http://127.0.0.1/note' -d '{
  "sha256_digest": "df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755",
  "body": "I am a cool markdown note"
}' -XPOST

PUT

The PUT for a note will allow the updating/resetting of the body field. This is pseudo PUT as it will only display put behaviour on the above field.

  • (Optional): body
    • default: ''
    • note for a sample in Snake
curl 'http://127.0.0.1/note/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -d '{
  "body": "I am a cool markdown note"
}' -XPUT

curl 'http://127.0.0.1/note/df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755' -d '{}' -XPUT

Notes

This route is used to access notes for multiple samples.

GET

The GET for notes will allow retrieval of multiple notes from Snake's database.

  • (Optional):sha256_digest
    • default: none
    • will limit returned notes to that of the given hash
curl 'http://127.0.0.1/notes'
curl 'http://127.0.0.1/notes?sha256_digest=df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755'

POST

The POST for a notes will create a notes for a given samples.

  • (Required): sha256_digest
    • the hash of the sample to create the note for
  • (Required): body
    • note for a sample in Snake
curl 'http://127.0.0.1/notes' -d '[
  {
    "sha256_digest": "df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755",
    "body": "I am a cool markdown note"
  }
]' -XPOST

curl 'http://127.0.0.1/notes' -d '[
  {
    "sha256_digest": "df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755",
    "body": "I am a cool markdown note"
  },
  {
    "sha256_digest": "509ff0dfba1798794948c303f5ef37401625c737f750e46773b93e5c77721ef0",
    "body": "I am another a cool markdown note"
  }
]' -XPOST

Scale Routes

These routes are used to interact with scales.

Supported Methods

/scale/<scale>
get

/scale/<scale>/commands
get

/scale/<scale>/interface
get, post

/scale/<scale>/upload
get, post

/scales
get

Scale

This route is used to retrieve information about a scale.

GET

The GET for a scale will obtain scale information such as: info, author, supported components, etc.

  • (Optional): reload
    • default: false
    • get Snake to reload its scales first
curl 'http://127.0.0.1/scale/hashes'

Scale Commands

This route is used to retrieve information about a scale's commands component.

GET

The GET for a commands component will provide information about scale's commands, such as: arguments, description, etc.

curl 'http://127.0.0.1/scale/hashes/commands'

Scale Interface

This route is used to retrieve information about a scale's interface component.

GET

The GET for an interface will provide information about scale's interface commands, such as: arguments, description, etc.

curl 'http://127.0.0.1/scale/cuckoo/interface'

POST

The POST for an interface will execute an interface command and return the result.

  • (Required): sha256_digest
    • hash for a sample in Snake
  • (Required): command
    • command to execute
  • (Optional): args
    • default: none
    • additional arguments provided by a command, these can be required or optional. See Scale Routes
  • (Optional): format
    • default: json
    • the format of the output field, supported types are command dependent
  • (Optional): type
    • default: pull
    • the type of interface command to execute: pull or push
curl 'http://127.0.0.1/scale/cuckoo' -d '{
  "command": "info",
  "sha256_digest": "df285ab34ad10d8b641e65f39fa11a7d5b44571a37f94314debbfe7233021755",
  "type": "pull"
}' -XPOST

Scale Upload

This route is used to retrieve information about a scale's upload component.

GET

The GET for an upload will provide information about scale's uploader, such as: arguments, information, etc.

curl 'http://127.0.0.1/scale/url/upload'

POST

The POST for an upload will execute the scale's upload to upload a sample.

  • (Optional): args
    • default: none
    • additional arguments provided by a command, these can be required or optional. See Scale Routes
  • (Optional): description
    • default: no change
    • description for a sample in Snake
  • (Optional): extract
    • default: false
    • attempt to extract the sample (must be a zip)
  • (Optional): name
    • default: no change
    • override the name of the sample
  • (Optional): password
    • default: none
    • password to handle password protected zips
  • (Optional): tags
    • default: no change
    • tags for a sample in Snake
curl 'http://127.0.0.1/scale/url' -d '{
  "args": {
    "url": "http://example.com/downloadme"
  },
  "description": "a sample file",
  "tags": "example"
}' -XPOST

Scales

This route is used to retrieve information about a scales.

GET

The GET for scales will obtain scale information for multiple scales.

  • (Optional): reload
    • default: false
    • get Snake to reload its scales first
curl 'http://127.0.0.1/scales'

Store Routes

These routes are used to interact with the store.

Supported Methods

/store/<sha256_digest>
get

/store
get

Store (Single)

This route is used to retrieve information about a given sample in the store (i.e. a valid hash for any file type).

GET

The GET for a sample in store will retrieve the metadata for a given sample (hash).

curl 'http://127.0.0.1/store/509ff0dfba1798794948c303f5ef37401625c737f750e46773b93e5c77721ef0'

Store

This route is used to retrieve information from the store (i.e. all sample - files & memories).

GET

The GET for store will allow retrieval of multiple samples from Snake's database.

  • (Optional): file_type
    • default: none
    • restrict the sample output on file type
  • (Optional): filter[FIELD]
    • default: none
    • key value pairs used to filter the documents returned
  • (Optional): limit
    • default: none
    • limits the number of documents returned
  • (Optional): operator
    • default: and
    • operator to apply to sort filters
  • (Operational): order
    • default: -1 (descending)
    • order to return the documents in
  • (Operational): sort
    • default: none
    • field to sort documents on
curl 'http://127.0.0.1/store'
curl 'http://127.0.0.1/store?limit=10'
curl 'http://127.0.0.1/store?order=1'
curl 'http://127.0.0.1/store?filter[name]=procdump&filter[tags]=tagstagstags'

Upload Routes

These routes are used to upload samples.

Supported Methods

/upload/file
post

/upload/files
post

/upload/memory
post

Upload File

This route is used to upload a file to Snake.

POST

The POST for a file upload will a file to Snake.

  • (Optional): description
    • default: no change
    • description for a sample in Snake
  • (Optional): extract
    • default: false
    • attempt to extract the sample (must be a zip)
  • (Optional): name
    • default: no change
    • override the name of the sample
  • (Optional): password
    • default: none
    • password to handle password protected zips
  • (Optional): tags
    • default: no change
    • tags for a sample in Snake
curl 'http://127.0.0.1/upload/file'
  -F 'file=@/bin/ls'
  -F 'name=ls'
  -F 'description=the ls binary'
  -XPOST

Upload Files

This route is used to upload multiple files to Snake.

POST

The POST for files upload will a file to Snake. NOTE: data array must be present for each file, even if empty (blame the code)!

  • (Optional): description
    • default: no change
    • description for a sample in Snake
  • (Optional): extract
    • default: false
    • attempt to extract the sample (must be a zip)
  • (Optional): name
    • default: no change
    • override the name of the sample
  • (Optional): password
    • default: none
    • password to handle password protected zips
  • (Optional): tags
    • default: no change
    • tags for a sample in Snake
curl 'http://127.0.0.1/upload/files'
  -F 'files[]=@./file1'
  -F 'files[]=@./file2'
  -F 'data=[
    {"name": "file1"},  # file1
    {"name": "file2"}   # file2
  ] -XPOST'

Upload Memory

This route is used to upload a memory to Snake.

POST

The POST for a memory upload will a memory to Snake.

  • (Optional): description
    • default: no change
    • description for a sample in Snake
  • (Optional): extract
    • default: false
    • attempt to extract the sample (must be a zip)
  • (Optional): name
    • default: no change
    • override the name of the sample
  • (Optional): password
    • default: none
    • password to handle password protected zips
  • (Optional): tags
    • default: no change
    • tags for a sample in Snake
curl 'http://127.0.0.1/upload/file'
  -F 'file=@~/Downloads/proc.dmp'
  -F 'name=explorer.dmp'
  -F 'description=a process dump of explorer.exe'
  -XPOST

curl 'http://127.0.0.1/upload/file'
  -F 'file=@~/Downloads/mem.raw.zip'
  -F 'name=pc.mem'
  -F 'description=a memory image'
  -F 'extract=true"
  -XPOST
Clone this wiki locally