File 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 theuploadUrland add an additional filekey 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.