Argus

Argus finds OTP and concurrency bugs in Elixir, Erlang and Gleam programs:

supervisor children that depend on each other but restart independently;
GenServers that deadlock calling each other;
races on a registered name or an ETS key.

It analyzes compiled .beam files and reports findings at the source lines involved.

Argus reports a restart dependency between two children of a one_for_one supervisor

Install and run

Argus runs its analyses on FlowLog engines: incremental Datalog that keeps its results up to date as your code changes, so a recompile re-derives only what an edit reached. The Mix integration requires Elixir 1.19 or later; prebuilt escripts require Erlang/OTP 28.

On macOS and Linux (arm64 or x86_64), a release ships its engines prebuilt: the first run downloads them once (about 70 MB, checked against the SHA-256 the package names) and needs no Rust, for argus's own analyses and for rules files of your own, which run in the generic engine the download carries. Elsewhere, argus builds its toolchain with Rust 1.88 or later, once: a few minutes. Every program then runs at once in the generic engine, and mix argus.flowlog build compiles engines for argus's own, which solve a large project up to twice as fast. ARGUS_FLOWLOG_PREBUILT=0 turns the download off, so argus builds everything itself. On Linux the prebuilt engines are linked static, so they run on any distribution: glibc or musl (Alpine), old or new, and NixOS. Where argus builds its own, it needs Rust and a C compiler (on NixOS, nix-shell -p cargo rustc gcc). A download that fails is tried again an hour later (or at once by mix argus.flowlog build), not at every compile.

ARGUS_OFFLINE=1 (or --offline on mix argus, mix argus.flowlog, the escript and rebar3 argus) makes no network call: argus uses prebuilt engines only once they are downloaded, Cargo builds from the crates ~/.cargo already holds, and priors: :live answers from the cache alone.

Build or fetch the engines ahead of time, in CI for instance, with mix argus.flowlog build, and see what is installed with mix argus.flowlog status. ARGUS_FLOWLOG_ENGINE=generic runs every program in the generic engine, and compiled builds an engine for every program, rules files of your own included. They live in ~/.cache/argus/flowlog (ARGUS_FLOWLOG_DIR names another directory, ARGUS_CARGO another cargo); mix argus.flowlog clean removes those of earlier releases.

Mix

Add Argus to your dependencies:

def deps do
  [
    {:argus_beam, "~> 0.24", only: [:dev, :test], runtime: false}
  ]
end

only: and runtime: false keep Argus out of production builds and releases.

Then fetch dependencies and run an analysis. mix argus compiles the project first.

mix deps.get
mix argus                 # configured analyses, or the default set
mix argus coupling ets    # selected analyses
mix argus --all           # all bug-finding analyses
mix argus --list          # available analyses and sets
mix argus --format json   # findings as JSON
mix argus --fail-above 0  # fail CI on any finding
mix argus --fail-on error # fail CI on an error-severity finding

To report findings on every compile, append the :argus compiler. Editors can show the findings as compiler diagnostics.

def project do
  [
    compilers: Mix.compilers() ++ if(Mix.env() in [:dev, :test], do: [:argus], else: []),
    argus: [analyses: [:default, :ets], severity: [mailbox: :error]]
  ]
end

List :argus only in the environments that have the dependency: in any other, such as a MIX_ENV=prod release build, Mix stops with "The task compile.argus could not be found".

By default, error findings fail the compiler run. mix argus uses --fail-above to decide whether findings fail the run.

rebar3

Add this to rebar.config, then run rebar3 argus. The plugin compiles the project and downloads the specified Argus escript.

{plugins, [rebar3_argus]}.
{argus_plugin, [{version, "0.24.0"}]}.
{argus, [{analyses, [default, ets]}]}.           % optional
{provider_hooks, [{post, [{compile, argus}]}]}.  % optional: run after compilation

Gleam, erlang.mk, or a directory of BEAM files

Install the escript with Mix:

mix escript.install hex argus_beam

Or download a prebuilt escript and its SHA-256 checksum from GitHub releases. Put argus on your PATH.

Build your project, then run:

argus                                 # current project
argus path/to/project --all
argus --project beams --ebin path/to/ebin

The escript reads existing BEAM files and warns about sources newer than their compiled files. Configuration goes in argus.config as Erlang terms. Gleam findings point to the generated Erlang source.

Choose analyses

The analyses marked ✓ run by default.

Analysis	Finds	Default
`startup`	blocking work, deadlocks and races during initialization	✓
`shutdown`	skipped cleanup, teardown that disrupts a peer, and programs a killed task leaves running	✓
`coupling`	processes that depend on each other but restart independently	✓
`structure`	invalid child specs, conflicting registrations and supervision mistakes	✓
`mailbox`	unhandled messages, missing replies and repeated resource acquisitions	✓
`failure`	swallowed errors, unchecked results and dropped resources	✓
`races`	check-then-act races on registered names, ETS keys or Mnesia records	✓
`blocking`	call cycles, nested waits, bottlenecks and unsafe distributed calls
`state_machine`	unreachable `gen_statem` states and terminal states that never stop
`ets`	table ownership, lifecycle and access-pattern problems
`effects`	effects inside a transaction that a rollback cannot undo
`unsafe_input`	atom exhaustion, unsafe deserialization and code execution
`exposure`	inspect-visible secrets and TLS connections without peer verification

Use analysis names or these sets in analyses::

:default: the analyses marked ✓;
:all: every analysis in the table;
:security: unsafe_input and exposure;
:effects: effects;
:otp: :all except :security and :effects.

The separate coverage analysis reports missing analysis information. Request it explicitly; --all excludes it.

severity: overrides the level for an analysis or set. To keep a finding you have looked at out of the report without hiding the rest of its module, name its analysis and where it is:

argus: [ignore: [findings: [{:shutdown, MyApp.Writer}, {:races, {MyApp.Reading, :retry, 2}}]]]

See the configuration reference for severity, ignore rules and compiler settings.

Interpret findings

Argus analyzes your project's code by default. Add --include-deps to analyze dependencies too. Dynamic calls and runtime configuration can leave gaps or produce findings that do not apply to a particular deployment.

Use the bug-class catalog to understand each finding's evidence and limits. Start with the contributor guide to capture a finding, inspect its rules and facts, or run a small extension. The analysis model and rule guide explain the implementation contracts.

License

MIT