Skip to content

Security: bemlerlabs/foreman

Security

SECURITY.md

Security policy

Foreman moves money between autonomous agents that do not trust each other. This document states what the project actually protects, how, and what you should do if you find a hole in it.

Reporting a vulnerability

Report privately through GitHub, not in a public issue:

Please do not post proof-of-concept transactions on the shared demo accounts, and do not drain the testnet demo escrow — it is the demonstration everyone else gets to inspect. Testnet funds only; there is no mainnet deployment to attack.

What is the trust root

Only the contract. contracts/foreman/ is the single place where a claim becomes true. Anything running off-chain — the Foreman agent, the board, the MCP plugin, the CLI, the market client — can be replaced by a malicious copy without changing what a payer receives, because the settleable facts (escrow balances, bid list, award, receipt hash, payout) live in contract state.

The consequence, which we accept deliberately: those off-chain parts are not hardened against a hostile operator, and the docs never claim they are.

Invariants that must not weaken

Invariant Where it is enforced Pinned by
Payment requires a receipt, and the receipt must be for this job's winner accept, attach_receipt accept_not_delivered_before_work, accept_twice_not_delivered, ONLY_WINNER
Identity is checked before state is read attach_receipt ordering attach_receipt_before_award_hits_only_winner_first
The winner is the awardee recorded on chain, never a caller-supplied account attach_receipt attach_receipt_not_awarded_after_accept
Bid count is bounded MAX_BIDS = 20 place_bid_max_bids_enforced
A stale delivery cannot capture escrow delivered-timeout + cancel_mutual refund_expired_ok_refunds_owner_and_marks_refunded, cancel_mutual_delivered_refunds
Exactly one counter-offer per job, and only by the Foreman identity counter_offer counter_offer_only_one_counter, counter_offer_stored_with_foreman_identity
Payout is 90 % of the posted budget (10 % foreman fee) — not of the winning bid accept (FOREMAN_FEE_NUM) accept_ok_updates_state_and_rep; live deltas +0.810000 to the worker and +0.089684…+0.089688 to the foreman (fee minus accept gas) in docs/EVIDENCE_LOG.md
A bid above the budget never enters the book place_bid place_bid_price_over_budget_rejected
A receipt that does not verify is an error, not a warning core/receipts/ephemora_adapter.py (verify raises) signature/tamper/replay pytest

If a change softens any row above, it needs a written decision in the PR, not a comment in the code.

Execution sandbox

Deliveries run inside ephemora_cell (Apache-2.0, vendored as a wheel in vendor/): no network, no host filesystem, memory and fuel capped, execution time bounded. The adapter hashes the egress log and the artifact bytes into the receipt, so "the sandbox let it talk out" would be visible in the record rather than assumed away. Receipt integrity is sha256 over JCS-canonical bytes, signed ES256 with a cell key that lives in keys/ (gitignored) and is generated by the operator.

What the sandbox does not give you: it does not make a wrong but honestly executed delivery correct. That is what the acceptance gate in core/acceptance/ is for, and it only machine-checks what is machine-checkable.

Keys, secrets and accounts

  • Separate accounts for owner, treasury, foreman and each swarm member (.env.example documents the shape); no shared signing key between roles.
  • Secrets are read from the environment. Nothing in this repo logs a secret value, and PR review treats a pasted key, JWT or aat_/naa_ token as an exposure: rotate it, then fix the history.
  • The Intents treasury path signs policies through a local loopback popup and keeps AGENT_EXECUTE off by default, so a quote is proven with dry:true before anything can spend.
  • One operator convenience has been removed from the working tree and is disclosed here rather than quietly dropped: ops/key-grant/ was a one-click page that granted a public key to a mainnet account. It held no private material — an account name and the public key being granted — and it could only act while that account's own wallet signed, but a testnet-only project has no business publishing the account, the key and the grant mechanism together. Nothing in the demo, the tests or the docs used it. Removal from the tree does not remove it from git history, so the key it named should be treated as known and revoked if it is still attached and not needed.

Out of scope

WASM binaries of third-party agents, the NEAR runtime itself, the public testnet RPCs we depend on (rate limits are documented, not security bugs), and social engineering of the demo accounts.

Known limits, stated plainly

  • The contract is not audited. It is a hackathon-scale implementation with a test suite (55 contract tests) and a fail-closed design, not a reviewed production system.
  • v1 stores the receipt as a hash anchor plus an ES256 signature from our own key. Verifying a fresh execution independently requires the WASM and its inputs; the repo ships both for the demo jobs precisely so that this is possible.
  • Board and sidecar are display-only. If they disagree with near view, the chain is right and the board is stale.

There aren't any published security advisories