Uploading data
In Finite State, you can upload binaries for analysis in Finite State Binary Analysis, or Test Results (from more than 100 security tools). The easiest way to do this is to use the helper functions in the SDK to help you create the entities you need, and then upload the data.
For the list of all supported upload types, see Supported Third Party File Types.
SDK Source Code Examples
Binary Quick Scan
When uploading a binary for analysis with Finite State Binary Analysis, you can optionally perform a Quick Scan. This is a lightweight scan that takes less than 10 minutes to complete, and provides a subset of the results of a full scan. This is useful for CI/CD pipelines, where you want to get a quick result, and then perform a full scan later.
To perform a quick scan, set the quick_scan parameter to True when calling create_new_asset_version_and_upload_binary:
import finite_state_sdk
# ... Create an Artifact in the Finite State App ...
# The Artifact's ID is the `asset_id` you will use in the code below
#... Set up your token and organization context ...
# Use this one-liner to create a new asset version, artifact, and test, and upload a binary
# for Finite State Binary Analysis (Quick Scan)
response = finite_state_sdk.create_new_asset_version_and_upload_binary(token, ORGANIZATION_CONTEXT, \
business_unit_id=business_unit_id, created_by_user_id=created_by_user_id, asset_id=asset_id,
version=version_name, file_path=file_path, product_id=None, quick_scan=True)
Binary Full Scan
The Binary Full Scan includes everything in the Quick Scan, plus additional binary analysis on individual executable and library files, and deeper analysis for software identification.
To perform a full scan, set the quick_scan parameter to False (or don't include it).
Uploading a Binary for Analysis
For a full code example, see finite-state-sdk-python/examples/uploading_a_binary.py.
Assuming you have already created your Asset, you typically create an AssetVersion using the version of the Artifact that you are testing. For example, if you are testing a binary, you would create an AssetVersion with the version of the binary you are testing (e.g. 1.0, 1.1, etc). If you are testing a source code repository or container, you would create an AssetVersion with the commit hash of the source code or container you are testing.
Here is an example of uploading a binary for Finite State Binary Analysis:
import finite_state_sdk
# business unit id is the id of the business unit you want to associate the upload with
# You can get this from the app by navigating to Accounts -> Business Unit and looking at the URL
business_unit_id = 12345
# created_by_user_id is the id of the user who is uploading the data
# You can get this from the app by navigating to Accounts -> Users and looking at the URL
created_by_user_id = 12345
# asset_id is the id of the Asset you want to associate the upload with
# Assuming this already exists, you can get this from the app by navigating to the Asset
# and looking at the URL
# For example:
# In this URL, https://platform.finitestate.io/artifacts/123456789
# the asset_id is 123456789
asset_id = 12345
# the `asset_version_name` is the name of the VERSION for the version you are creating,
# so it will be something like "1.0.0" or a git commit hash like "a1b2c3d4"
# Usually your build process will generate this
version_name = '1.0.0'
# The file you are uploading from your local filesystem
file_path = '/path/to/binary/file'
# the `product_id` is the id of the Product you want to associate the upload with, if any
product_id = 12345
# Use this one-liner to create a new asset version, artifact, and test, and upload a binary
# for Finite State Binary Analysis (Quick Scan)
response = finite_state_sdk.create_new_asset_version_and_upload_binary(token, ORGANIZATION_CONTEXT, \
business_unit_id=business_unit_id, created_by_user_id=created_by_user_id, asset_id=asset_id,
version=version_name, file_path=file_path, product_id=None, quick_scan=True)
Uploading Test Results
For a full code example, see finite-state-sdk-python/examples/uploading_test_results.py.
The easiest way to upload test results via API is to use the SDK's `upload_. For more details, see the SDK section of the documentation.
Assuming you have already created your Asset, you typically create an AssetVersion using the version of the Artifact that you are testing. For example, if you are testing a source code repository or container, you would create an AssetVersion with the commit hash of the source code or container you are testing.
Here is an example of uploading Test Results from a third party scanner such as an SCA or SAST tool:
import finite_state_sdk
# business unit id is the id of the business unit you want to associate the upload with
# You can get this from the app by navigating to Accounts -> Business Unit and looking at the URL
business_unit_id = 12345
# created_by_user_id is the id of the user who is uploading the data
# You can get this from the app by navigating to Accounts -> Users and looking at the URL
created_by_user_id = 12345
# asset_id is the id of the Asset you want to associate the upload with
# Assuming this already exists, you can get this from the app by navigating to the Asset
# and looking at the URL
# For example:
# In this URL, https://platform.finitestate.io/artifacts/123456789
# the asset_id is 123456789
asset_id = 12345
# the `asset_version_name` is the name of the VERSION for the version you are creating,
# so it will be something like "1.0.0" or a git commit hash like "a1b2c3d4"
# Usually your build process will generate this
version_name = '1.0.0'
# The file you are uploading from your local filesystem
file_path = '/path/to/file'
# the `product_id` is the id of the Product you want to associate the upload with, if any
product_id = 12345
# Use this one-liner to create a new asset version, artifact, and test, and upload a
# test result file
# NOTE: You need to specify the `test_type`. In this case we are uploading a CycloneDX
# SBOM, so the test type is "cyclonedx"
response = finite_state_sdk.create_new_asset_version_and_upload_test_results(token, ORGANIZATION_CONTEXT, \
business_unit_id=business_unit_id, created_by_user_id=created_by_user_id, asset_id=asset_id, \
version=version_name, file_path=file_path, product_id=None, \
artifact_description="Source Code Repository", test_type="cyclonedx")
Using the API Directly
If you are not using the SDK, you can use the API directly, which has several additional requirements for creating the required entities.
API Pre-Requisites
To upload files, you need to have or create the following entities:
AssetAssetVersionArtifactTestUser(to associte with the upload)Group(also known as Business Unit, to associate with the upload)Product(if you want to associate the upload with a Product)
Most users create an Asset in the application UI, and may or may not associate it with a Product. You can also create these entities using the API.
For more details, see the Creating Entities section of the API documentation.
Getting Existing Entities
To associate your upload correctly, you need to get or create the entities listed above.
Getting an Asset
To upload your file, you need to know the Asset's id. You can get this listing all the Assets, or from the web application.
In the web application, the Asset id is the number at the end of the URL when you are viewing the Asset (in the app this is referred to as "Artifact"). (e.g. https://platform.finitestate.io/artifacts/12345)
In CI/CD pipelines, you typically create an Asset in the application UI, and then use the Asset's id in your CI/CD pipeline.
assets = fs_sdk.get_all_assets(AUTH_TOKEN, ORGANIZATION_CONTEXT)
# Get the Asset id (replace 0 with the index of the AssetVersion you want)
asset_id = assets[0]['id']