This page will help you get started with Intake API.
In most deployments, files are collected automatically using the file forwarder. Stairwell can process any file you upload, including those submitted via API. Once a file is uploaded, it will be processed like all other files. One use-case is to upload a file to Stairwell and then detonate it in our bundled sandbox, all in one action.
Our file upload occurs in two steps: preflight and upload. The preflight step allows Stairwell to de-duplicate files and save you from having to upload things more than once. If the file hasn’t been seen before, the preflight response will include details on where to upload the file. File uploads require that you have an Asset ID
to perform the upload. This can be found in the web UI, and you can use either the __DefaultAsset__
or create a brand new one with our Create Asset API.
Preflight
curl --request POST \
--url https://http.intake.app.stairwell.com/v2021.05/upload \
--header 'Content-Type: application/json' \
--data '{
"asset": {
"id": "<ASSET ID>"
},
"files": [{
"filePath": "<FILEPATH>",
"expected_attributes": {
"identifiers": [{
"sha256": "<SHA256>"
}]
}
}]
}'
If the file already exists in your Stairwell environment, the action will be NO_ACTION_ALREADY_EXISTS
, and you can stop here.
If Stairwell has not seen the file before in your environment, the API will respond with the action UPLOAD
and an uploadUrl
. Here’s an example:
{
"fileActions": [
{
"filePath": "<FILEPATH>",
"expectedAttributes": {
"identifiers": [
{
"sha256": "<SHA256>"
}
]
},
"uploadUrl": "https://storage.googleapis.com/blobstore-intake-staging-stairwell-prod/",
"fileField": "file",
"method": "POST",
"fields": {
"key": "2022-12-16T13:09Z/37297b34-efe5-4925-8908-61924e2e5d14",
"policy": "eyJjb25kaXRpb25zIjptMTZUMTM6MTk6NDhaIn0=",
"x-goog-algorithm": "GOOG4-RSA-SHA256",
"x-goog-credential": "[email protected]/20221216/auto/storage/goog4_request",
"x-goog-date": "20221216T130948Z",
"x-goog-meta-asset-id": "<ASSET ID>",
"x-goog-meta-file-detonate": "DETONATION_PLAN_UNSPECIFIED",
"x-goog-meta-file-format": "RAW",
"x-goog-meta-file-path": "C:\\Users\\frank\\test.db",
"x-goog-meta-sha256": "test",
"x-goog-signature": "4a34fef62a4d708c347aac351d"
},
"headers": {
"sha256": "test"
},
"action": "UPLOAD"
}
]
}
Upload
If preflight responds with the action UPLOAD
, you can now upload the file to Stairwell using the uploadUrl
from the response. POST
the contents of the response's fields
as multipart/form-data
to theuploadUrl
and add an additional file
key with the raw contents of the file. An example payload is:
curl --request POST \
--url https://storage.googleapis.com/blobstore-intake-staging-stairwell-prod \
--header 'Content-Type: multipart/form-data' \
--form 'key=2022-12-16T13:09Z/37297b34-efe5-4925-8908-61924e2e5d14' \
--form 'policy=eyJjb25kaXRpb25zIjptMTZUMTM6MTk6NDhaIn0=' \
--form 'x-goog-algorithm=GOOG4-RSA-SHA256' \
--form 'x-goog-credential=intake-http@stairwell-prod.iam.gserviceaccount.com/20221216/auto/storage/goog4_request' \
--form 'x-goog-date=20221216T130948Z' \
--form 'x-goog-meta-asset-id=<ASSET ID>' \
--form 'x-goog-meta-file-detonate=DETONATION_PLAN_UNSPECIFIED' \
--form 'x-goog-meta-file-format=RAW' \
--form 'x-goog-meta-file-path=<FILEPATH>' \
--form 'x-goog-meta-sha256=<SHA256>' \
--form 'x-goog-signature=4a34fef62a4d708c347aac351d' \
--form 'file=@<FILEPATH>'
Note: A successful upload will only respond with a RC 204 and nothing else.
Detonation: If you wish to detonate the file automatically, change the x-goog-meta-file-detonate
value from DETONATION_PLAN_UNSPECIFIED
to DETONATE
Detonations triggered in this fashion may take longer as detonations triggered via the UI are prioritized over others.