mix_safe – Mix Plugin

mix_safe integrates SAFE into Mix projects (Elixir). It manages the SAFE binary automatically — downloading and caching it — and exposes SAFE commands directly through Mix. Umbrella projects are supported.

Installation

Add mix_safe to your dependencies in mix.exs:

mix.exs

defp deps do
  [
    {:mix_safe, "~> 1.0", only: [:dev, :test], runtime: false}
  ]
end

Then fetch the dependency:

mix deps.get

Commands

Command	Description
mix safe fingerprint	Generates .safe/config.json and a fingerprint.json for licensing
mix safe analyse	Runs security analysis. Exits with code 2 if vulnerabilities are found
mix safe download	Pre-downloads the SAFE binary without running a scan
mix safe version	Displays the plugin version and the SAFE binary version

Workflow

1. One-time setup — run mix safe fingerprint locally to generate .safe/config.json. Commit this file to your repository.
2. CI — run mix safe analyse in your pipeline. The plugin downloads the binary on first use and runs the analysis.

Binary Management

The SAFE binary is stored at _build/safe/safe. The exact version is locked in safe.lock at the root of your project — commit this file so every developer and CI run uses the same binary version.

On the first invocation, the binary is downloaded automatically. Subsequent runs use the cached copy.

tip

Add _build/safe to your CI cache, keyed on the contents of safe.lock. This avoids downloading the binary on every pipeline run.

CI/CD

GitHub Actions example

.github/workflows/safe.yml

name: SAFE Security Scan

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]

jobs:
  safe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: erlef/setup-beam@v1
        with:
          otp-version: '26'
          elixir-version: '1.16'

      - name: Restore plugin binary cache
        uses: actions/cache@v4
        with:
          path: _build/safe
          key: safe-binary-${{ hashFiles('safe.lock') }}
          restore-keys: safe-binary-

      - name: Restore analysis state cache
        uses: actions/cache@v4
        with:
          path: ~/.safe
          key: safe-state-${{ github.ref }}-${{ github.sha }}
          restore-keys: |
            safe-state-${{ github.ref }}-
            safe-state-

      - name: Install dependencies
        run: mix deps.get

      - name: Compile
        run: mix compile

      - name: Run SAFE analysis
        run: mix safe analyse
        env:
          SAFE_LICENSE: ${{ secrets.SAFE_LICENSE }}

For more CI examples (GitLab, CircleCI), see the Setting Up in CI/CD page.

Exit Codes

Code	Meaning
0	Analysis completed successfully — no vulnerabilities found.
1	An error occurred (bad configuration, missing license, etc.).
2	Analysis completed — vulnerabilities were found.