HOW-TO GUIDES

Upload files for a run

Turn local files into artifact IDs, then choose their paths inside the tool.

1. Upload and seal a file

Save the example as upload_file.py, place sample.bin next to it, and run it with your API URL and token set. It calculates the size and SHA-256, declares the upload, sends the bytes, and seals the artifact. Save the printed artifact ID.

2. Choose a name for the tool

Put the returned ID in invocation.files, for example {"path":"samples/input.bin","artifact_id":"artifact_..."}. The tool sees that file under /tmp/work/samples/input.bin. Use samples/input.bin in its arguments.

3. Add the other inputs

Repeat for each rule, source file or configuration file. You can upload once and reuse a sealed artifact in multiple runs. A directory is represented by named files such as src/app.py and src/helpers.py; uploading a ZIP does not automatically extract it.

Empty files and executable scripts

Use empty_files for empty inputs and directories for empty directories. Set executable: true on a staged script if the tool needs to execute it.

If an upload fails

A checksum mismatch usually means the declared hash or size came from different bytes. Recalculate both and create a new upload. Sealing must succeed before an artifact can be submitted to a run.

Inputs are limited to 8 MiB per artifact and 32 MiB total per run, including stdin. See Limits and environments for the complete limits.

import os import httpx api = httpx.Client( base_url=os.environ["SECURITY_RUN_URL"].rstrip("/"), headers={"Authorization": "Bearer " + os.environ["SECURITY_RUN_API_KEY"]}, timeout=30, ) import hashlib, uuid from pathlib import Path def upload(path): data = Path(path).read_bytes() key = str(uuid.uuid4()) response = api.post("/v1/artifacts", headers={"Idempotency-Key": key}, json={ "filename": Path(path).name, "size": len(data), "sha256": hashlib.sha256(data).hexdigest(), }) response.raise_for_status() artifact = response.json() api.put(artifact["upload_url"], content=data).raise_for_status() response = api.post(artifact["complete_url"], headers={"Idempotency-Key": key}) response.raise_for_status() return response.json()["id"] print(upload("sample.bin"))