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.

Install and run

Install Soufflé on your PATH. The Mix integration requires Elixir 1.19 or later; prebuilt escripts require Erlang/OTP 28.

Mix

Add Argus to your dependencies:

def deps do
  [
    {:argus_beam, "~> 0.20"}
  ]
end

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

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

def project do
  [
    compilers: Mix.compilers() ++ [:argus],
    argus: [analyses: [:default, :ets], severity: [mailbox: :error]]
  ]
end

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.20.1"}]}.
{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.

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. 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. For contributors, the analysis model and rule guide explain the implementation.

License

MIT