Module properties 

The forge properties command: several agents look for bugs in the targets independently and in parallel, each in one session in its own copy of the project, and prove each bug with a failing test. Forge runs the tests of every agent again in a fresh copy on every seed, reports a bug only when enough agents agree on its root cause, and keeps one copy of each passing test file. An optional verifier then tries to disprove each reported bug.

Re-exports

use crate::cmd::test::RerunFailure; 🔒

use crate::result::TestResult; 🔒

use crate::result::TestStatus; 🔒

use crate::workspace; 🔒

use alloy_primitives::U256; 🔒

use alloy_primitives::keccak256; 🔒

use clap::Parser; 🔒

use eyre::Context; 🔒

use eyre::Result; 🔒

use eyre::ensure; 🔒

use eyre::eyre; 🔒

use foundry_cli::opts::BuildOpts; 🔒

use foundry_cli::utils::LoadConfig; 🔒

use foundry_common::fs::canonicalize_path; 🔒

use foundry_common::sh_println; 🔒

use foundry_common::sh_warn; 🔒

use foundry_compilers::Graph; 🔒

use foundry_compilers::cache::SOLIDITY_FILES_CACHE_FILENAME; 🔒

use foundry_compilers::compilers::Language; 🔒

use foundry_compilers::compilers::multi::MultiCompilerLanguage; 🔒

use foundry_compilers::compilers::multi::MultiCompilerParser; 🔒

use foundry_compilers::compilers::solc::Solc; 🔒

use foundry_compilers::utils::source_files_iter; 🔒

use foundry_config::Config; 🔒

use foundry_config::DenyLevel; 🔒

use foundry_config::impl_figment_convert; 🔒

use foundry_evm::fuzz::CounterExample; 🔒

use regex::Regex; 🔒

use serde::Deserialize; 🔒

use serde::Deserialize; 🔒

use serde::Serialize; 🔒

use serde::Serialize; 🔒

use std::cmp::Reverse; 🔒

use std::collections::BTreeMap; 🔒

use std::collections::BTreeSet; 🔒

use std::collections::HashSet; 🔒

use std::ffi::OsString; 🔒

use std::fs; 🔒

use std::io; 🔒

use std::io::Write; 🔒

use std::ops::Add; 🔒

use std::path::Path; 🔒

use std::path::PathBuf; 🔒

use std::process::Command; 🔒

use std::process::ExitStatus; 🔒

use std::process::Output; 🔒

use std::process::Stdio; 🔒

use std::sync::LazyLock; 🔒

use std::sync::atomic::AtomicUsize; 🔒

use std::sync::atomic::Ordering; 🔒

use std::thread; 🔒

use std::time::Duration; 🔒

use std::time::Instant; 🔒

use std::time::SystemTime; 🔒

use tempfile::TempDir; 🔒

use toml_edit::DocumentMut; 🔒

use rustix::process::Pid; 🔒 Unix

use rustix::process::Signal; 🔒 Unix

use rustix::process::kill_process_group; 🔒 Unix

use std::os::unix::process::CommandExt; 🔒 Unix

use std::sync::Mutex; 🔒 Unix

Modules

matcher 🔒

The root-cause matcher: decides which failing tests of different agents prove the same bug.

Structs

AgentFailure 🔒

A test of one agent that fails on every seed.

AgentInputs 🔒

The inputs that every agent shares.

BugGroup 🔒

The failing tests of all agents that have one root cause.

Campaign 🔒

The settings of one forge properties run.

Evidence 🔒

A quote from a file that supports a verdict.

Failure 🔒

A test that fails on every seed.

Judgment 🔒

The verdict file of a verifier.

PropertiesArgs

Run agents that prove bugs with failing tests and report the bugs that they agree on.

Rejected 🔒

Files of an agent that Forge did not run.

RunDirs 🔒

The output directories that a run reserved. The ones it left empty are removed on drop.

Sandbox 🔒

Builds and runs generated code in temporary copies of the project. Generated code runs outside the sandbox of whatever wrote it, so a copy leaves out hidden root entries such as .env and agent settings, and Forge runs in it with only a few environment variables.

Session 🔒

What one agent session left.

TestFile 🔒

A Solidity file that an agent wrote, by its path relative to the project root.

TestRun 🔒

The tests of some files, run on every seed.

Usage 🔒

Model usage that an agent reports.

Verification 🔒

What one verifier session left for a bug group.

Enums

Verdict 🔒

The verdict of a verifier.

Constants

AGENT_CONFIG 🔒

Agent settings and instruction files that a workspace leaves out at every level. Settings can hold hooks that run commands on the host. CLAUDE.md and AGENTS.md are project docs, but they steer the agents that work in the copy, so a user who wants them passes them with --context. Entries of dependency directories are links, so they keep their own files.

DEFAULT_AGENTS 🔒

On 12 held-out cases, four small-model agents with a quorum of two found bugs in as many cases as five (8.6 against 9.0 of 12, a tie in a bootstrap over cases) at four fifths of the cost. With a quorum of two, they kept no report that reviewers labelled wrong, because wrong claims of independent agents rarely repeat.

DEFAULT_QUORUM 🔒

PASSED_ENV 🔒

The environment variables that builds and test runs of generated code see, besides HOME, FOUNDRY_PROFILE, and the seed settings. Generated tests run outside the agent’s sandbox, so they must not read the secrets of Forge’s environment with the env cheatcodes.

RUN_TIMEOUT 🔒

How long one Forge build or test run in a workspace can take.

SELECT_ALL_TESTS 🔒

Overrides configured test filters, so they cannot hide generated tests. $^ matches no contract or test name, and no project file is under /forge-properties-none.

SESSION_POLL 🔒

How often Forge checks whether an agent session with a timeout has exited. Sessions take minutes, so this adds no noticeable delay.

VERIFY_PROMPT 🔒

The task of a verifier session. The placeholders are the targets, the group file, the verdict file, and the tests of the group.

Statics

BLOCKED 🔒

The errors of what Forge blocks in its workspaces: vm.ffi without --allow-ffi, network cheatcodes without --allow-network, env cheatcodes, which see only a few variables, and inline config that --restrict-inline-config refuses.

COMMENT 🔒

Solidity line and block comments.

CONTRACT 🔒

A contract declaration and its name.

SESSIONS 🔒 Unix

The process groups of the running agent sessions, which Forge ends if it is interrupted.

Functions

collect_tests 🔒

Returns the Solidity files under the output directory out of a workspace, by path relative to the workspace, in path order. Links are not followed, and out itself must not be one. A file whose path has a glob character is rejected: Forge selects the files to run by a glob.

collected_imports 🔒

Returns the collected files that each collected file imports, directly or not.

copy_build_output 🔒

Copies the build output and the compiler cache of a built workspace into another workspace. The copy clones files where the file system can (APFS, Btrfs, XFS).

copy_project_tree 🔒

Copies a project directory into a workspace, without Git data, the skipped paths, agent settings and instructions (AGENT_CONFIG), and, at the project root, hidden entries such as .env.

ensure_inside 🔒

Fails if the nearest existing ancestor of path resolves outside root, for example through a linked directory.

failure_reason 🔒

Appends the counterexample calls to a failure reason.

group_failures 🔒

Groups the failing tests of all agents by root cause with the root-cause matcher. Groups with a claim come first, then groups with more agents.

group_files 🔒

Returns the files of a group: the files of its failing tests, with the files of the same agent that they import, directly or not.

kept_files 🔒

Returns the files whose tests all pass on every seed, with the files that they import. A passing file that imports a file with a failing test is not kept.

project_fingerprint 🔒

Returns the size and modification time of each file that workspaces share with the project, by path relative to the root: the files in the dependencies directories, whose entries workspaces link, and behind links that lead outside the project. Workspaces copy every other file, so a change to one cannot come from an agent. Hidden entries and the build and cache directories are skipped. Each directory is read once.

read_usage 🔒

Reads the usage file of an agent or verifier. A missing file is no usage, and an invalid one is a warning.

restrict_config 🔒

Turns off ffi unless allow_ffi, and removes the RPC and Etherscan settings unless allow_network. Every workspace of a Sandbox writes this config, so no generated test can call vm.ffi or reach an endpoint that the config names. Config ignores FFI environment variables.

run_session 🔒

Runs a session command in its own process group until it exits or reaches the timeout in seconds, then ends the process group, so no process that the session started keeps running. Returns None if the session reached the timeout.

seed_dir 🔒

Returns the directory for one seed’s builds and persisted state in a workspace.

session_prompt 🔒

Returns the task of an agent session. On 26 held-out cases, plain independent small-model audits with a task of this kind found 0.05 to 0.10 more planted bugs at every spend level than agents that returned candidate JSON in short rounds.

shorten 🔒

Keeps both ends of a long tool output. Many tools print the decisive error last.

stderr 🔒

Returns stderr without compiler warning blocks and keeps both ends when it is still long. Warnings can fill the limit before the decisive error, and many tools print the error last. Without a compiler error, as with deny = "warnings", the warnings are the errors and stay.

suite_results 🔒

Returns every test result in Forge’s JSON output with its contract and test name.

test_claim 🔒

Returns the comment right above a test function, without comment markers, as one line. The function is the first one with this name after the contract declaration and before the next one. Declarations are searched outside comments, so a claim such as the contract pays twice is not a declaration.

test_display_name 🔒

Returns Contract::test for a test identity.

test_path 🔒

Returns the file of a test identity.

test_results 🔒

Returns every test result in Forge’s JSON output, with one result per invariant predicate of a merged invariant campaign.

verify_prompt 🔒

Returns the task of a verifier session.

Type Aliases

Fingerprint 🔒

The size and modification time of each project file, by path relative to the root.