{"id":20433833,"url":"https://github.com/flashbots/system-api","last_synced_at":"2025-10-07T10:54:34.507Z","repository":{"id":259470393,"uuid":"860350432","full_name":"flashbots/system-api","owner":"flashbots","description":"Interface between TDX operator and services inside","archived":false,"fork":false,"pushed_at":"2025-09-18T17:18:40.000Z","size":193,"stargazers_count":9,"open_issues_count":2,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-09-24T12:38:39.222Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flashbots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-20T09:16:53.000Z","updated_at":"2025-09-18T17:18:16.000Z","dependencies_parsed_at":"2025-01-16T03:18:50.275Z","dependency_job_id":null,"html_url":"https://github.com/flashbots/system-api","commit_stats":null,"previous_names":["flashbots/system-api"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/flashbots/system-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fsystem-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fsystem-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fsystem-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fsystem-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flashbots","download_url":"https://codeload.github.com/flashbots/system-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fsystem-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278762921,"owners_count":26041444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T08:21:29.064Z","updated_at":"2025-10-07T10:54:34.490Z","avatar_url":"https://github.com/flashbots.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# System API\n\n[![Goreport status](https://goreportcard.com/badge/github.com/flashbots/system-api)](https://goreportcard.com/report/github.com/flashbots/system-api)\n[![Test status](https://github.com/flashbots/system-api/actions/workflows/checks.yml/badge.svg?branch=main)](https://github.com/flashbots/system-api/actions?query=workflow%3A%22Checks%22)\n\nAn interface between TDX VM services and the operator. Used in [BuilderNet](https://buildernet.org/).\n\nFeatures:\n\n- **Event log**: Services inside a TDX instance can record events they want exposed to the operator\n used to record and query events. Useful to record service startup/shutdown, errors, progress updates,\n hashes, etc.\n- **Actions**: Ability to execute shell commands via API\n- **File uploads**\n- **HTTP Basic Auth** support\n- **TLS encryption support**\n\nNotes:\n\n- Configuration through config file (see [`systemapi-config.toml`](./systemapi-config.toml))\n- Actions and file uploads show up in the event log\n\n---\n\n## Getting started\n\n```bash\n# Start the server\nmake run\n\n# Add events\necho \"hello world\" \u003e pipe.fifo\ncurl --insecure https://localhost:3535/api/v1/new_event?message=this+is+a+test\n\n# Execute actions\ncurl --insecure https://localhost:3535/api/v1/actions/echo_test\n\n# Upload files\ncurl --insecure --data-binary \"@README.md\" https://localhost:3535/api/v1/file-upload/testfile\n\n# Get event log\ncurl --insecure https://localhost:3535/logs\n2024-11-05T22:03:23Z     hello world\n2024-11-05T22:03:26Z     this is a test\n2024-11-05T22:03:29Z     [system-api] executing action: echo_test = echo test\n2024-11-05T22:03:29Z     [system-api] executing action success: echo_test = echo test\n2024-11-05T22:03:31Z     [system-api] file upload: testfile = /tmp/testfile.txt\n2024-11-05T22:03:31Z     [system-api] file upload success: testfile = /tmp/testfile.txt - content: 1991 bytes\n\n# Set basic auth secret\ncurl --insecure --data \"foobar\" https://localhost:3535/api/v1/set-basic-auth\n\n# Get logs with basic auth (otherwise will be rejected with Unauthorized)\ncurl --insecure --user admin:foobar https://localhost:3535/logs\n```\n\n---\n\n## Event log\n\nEvents can be added via local named pipe (i.e. file `pipe.fifo`) or through HTTP API:\n\n```bash\n# Start the server\n$ make run\n\n# Add events\n$ echo \"hello world\" \u003e pipe.fifo\n$ curl --insecure https://localhost:3535/api/v1/new_event?message=this+is+a+test\n\n# Query events (plain text or JSON is supported)\n$ curl --insecure https://localhost:3535/logs\n2024-10-23T12:04:01Z     hello world\n2024-10-23T12:04:07Z     this is a test\n```\n\n---\n\n ## Actions\n\n Actions are shell commands that can be executed via API. The commands are defined in the config file,\n see [systemapi-config.toml](./systemapi-config.toml) for examples.\n\nActions are recorded in the event log.\n\n```bash\n# Start the server\n$ make run\n\n# Execute the example action\n$ curl --insecure https://localhost:3535/api/v1/actions/echo_test\n```\n\n---\n\n## File Uploads\n\nUpload destinations are defined in the config file (see [systemapi-config.toml](./systemapi-config.toml)).\n\nFile uploads are recorded in the event log.\n\n```bash\n# Start the server\n$ make run\n\n# Upload the file\n$ curl --insecure --data-binary \"@README.md\" https://localhost:3535/api/v1/file-upload/testfile\n```\n\n---\n\n## HTTP Basic Auth\n\nAll API endpoints can be protected with HTTP Basic Auth.\n\nThe API endpoints are initially unauthenticated, until a secret is configured\neither via file or via API. If the secret is configured via API, the salted SHA256\nhash is be stored in a file (specified in the config file) to enable basic auth protection\nacross restarts.\n\nThe config file ([systemapi-config.toml](./systemapi-config.toml)) includes `basic_auth_secret_path` (and `basic_auth_secret_salt`).\n- If the file exists and is not empty, then the APIs are authenticated for passwords that match the salted hash in this file.\n- If the file exists and is empty, then the APIs are unauthenticated until a secret is configured.\n- If this file is specified but doesn't exist, system-api will create it (empty).\n\nExample:\n\n```bash\n# The included systemapi-config.toml uses basic-auth-secret.txt for basic_auth_secret_path\ncat systemapi-config.toml\n\n# Start the server\nmake run\n\n# Initially, requests are unauthenticated\ncurl --insecure https://localhost:3535/livez\n\n# Set the basic auth secret. From here on, authentication is required for all API requests.\ncurl --insecure --data \"foobar\" https://localhost:3535/api/v1/set-basic-auth\n\n# Check that hash was written to the file\ncat basic-auth-hash.txt\n\n# API calls with no basic auth credentials are provided fail now, with '401 Unauthorized' because\ncurl --insecure https://localhost:3535/livez\n\n# API calls work if correct basic auth credentials are provided\ncurl --insecure --user admin:foobar https://localhost:3535/livez\n\n# The update also shows up in the logs\ncurl --insecure --user admin:foobar https://localhost:3535/logs\n\n# You can also update the basic auth secret:\ncurl --insecure --user admin:foobar --data \"new_secret\" https://localhost:3535/api/v1/set-basic-auth\n```\n\n---\n\n## TLS encryption support\n\nTLS encryption is supported. System-API can load the certificate and key from local files (which it can also generate if missing).\n\nThe config file ([systemapi-config.toml](./systemapi-config.toml)) includes `tls_cert_path` and `tls_key_path` for the certificate and key files, and\na few other options:\n\n```toml\n[general]\n# TLS configuration\ntls_enabled = true\ntls_create_if_missing = true\ntls_cert_hosts = [\"localhost\", \"\"]\ntls_cert_path = \"cert.pem\"\ntls_key_path = \"key.pem\"\n```\n\nIf `tls_enabled` is set to `false`, TLS is disabled and regular HTTP requests will work just fine. If `tls_enabled` is set to `true`, requests will be served over HTTPS.\n\nIf `tls_create_if_missing` is set to `true`, system-api will generate a self-signed certificate and key if the files are missing. If set to `false`, system-api will fail to start if the files are missing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflashbots%2Fsystem-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflashbots%2Fsystem-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflashbots%2Fsystem-api/lists"}