How to use the File Reputation API

Learn how to utilize the Inception API to search across files and malware feeds

Table of Contents

1. Overview
2. Access the API
3. Example output

Overview

The Inception File Reputation API enables organizations to leverage file data within Inception for data enrichment. With this API, you will be able to search across all files Inception has received from your organization, along with files received from the Stairwell global malware feeds.

Access the API

Use the following information to access the API:

• HTTP REST endpoint: https://reputation.app.stairwell.com/api/v3/files/<FILE HASH>
• Authentication: Pass X-ApiKey header with your Auth Token

Example with curl:

curl -H "X-Apikey: YOURAPIKEY" https://reputation.app.stairwell.com/api/v3/files/<FILE HASH>

Example output

The following are example outputs, similar to the outputs you will see when a file is found or when a file is not found.

File found:

{
    "type": "file",
    "id": "f89d3d2177a4ad5a4995fd2bedaf13c6de2726e14f1367c21cdbb5c776aa1c7f",
    "links": {
        "self": "/api/v3/files/f89d3d2177a4ad5a4995fd2bedaf13c6de2726e14f1367c21cdbb5c776aa1c7f"
    },
    "data": {
        "attributes": {
            "md5": "68927422419023003c40ecd438981af1",
            "sha1": "6303420a19756a69b436fd1e2902437ff0734613",
            "sha256": "f89d3d2177a4ad5a4995fd2bedaf13c6de2726e14f1367c21cdbb5c776aa1c7f",
            "size": 6113792,
            "creation_date": 1646274587,
            "names": [
                "C:\\Users\\ida\\go\\hello\\/hello.exe"
            ],
            "meaningful_name": "C:\\Users\\ida\\go\\hello\\/hello.exe",
            "times_submitted": 1,
            "type_description": "EXE",
            "crowdsourced_yara_results": [
                {
                    "rule_name": "Methodology_Codelang_Golang_BuildId_Catchall"
                },
                {
                    "rule_name": "Methodology_Codelang_Golang_Strings_PE"
                },
                {
                    "rule_name": "Methodology_Algorithm_SHA256_Constants"
                },
                {
                    "rule_name": "Methodology_PotentialCredentialHarvester"
                }
            ],
            "occurrences": [
                {
                    "environment": {
                        "id": "2FPYDD-8LP9XU-VYQAAC-VTRF29MT",
                        "name": "Ida Bear Sandbox"
                    },
                    "assets": [
                        {
                            "id": "AD64SQ-C3VABC-8HJN6L-LF2CR999",
                            "name": "WORKGROUP\\SW-MJW-CRD-1"
                        }
                    ]
                }
            ],
            "mal_eval_result": {
                "label": "onlinegames",
                "probability_bucket": "PROBABILITY_VERY_HIGH"
            },
            "magic": "EXE",
            "imphash": "c7269d59926fa4252270f407e4dab043",
            "ssdeep": "98304:Q4xcDSb5mWNPEU8O/41EhETAN4EwKy+QJ:9yWBEjOd54+Q"
        }
    }
}

File not found:

{
	"data": null,
	"meta": null,
	"links": {},
	"error": {
		"code": "NotFound",
		"message": "no object found for identifier: sha256:\"e89d3d2177a4ad5a4995fd2bedaf13c6de2726e14f1367c21cdbb5c776aa1c7f\""
	}
}