MixAudit

MixAudit performs a security scan by comparing two datasets:

1. Security Advisories: Fetched from the elixir-security-advisories repository.
2. Project Dependencies: Extracted from the mix.lock files in your project.

The tool iterates through each dependency and checks if its package name and version match any known vulnerable version ranges defined in the security advisories. If a match is found, a vulnerability is added to the report.

It is important to distinguish between these two tasks:

• mix deps.audit (MixAudit): Scans dependencies for reported security vulnerabilities using the elixir-security-advisories database.
• mix hex.audit (Hex): A built-in Hex task that identifies dependencies that have been marked as retired.

Both are useful for dependency management but serve different purposes.

If you prefer not to add MixAudit to your project's mix.exs, you can install it globally as an escript. Note that when using the escript, you will call the executable directly instead of using the mix deps.audit task.

$ mix escript.install hex mix_audit

To use MixAudit within a specific Elixir project, add it to your deps function in mix.exs. It is recommended to restrict it to :dev and :test environments and set runtime: false since it is a development tool.

After updating mix.exs, run mix deps.get and mix deps.compile to complete the installation.

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

The mix_audit tool allows you to audit your Elixir project's dependencies against known security advisories. It identifies vulnerable packages and generates a security report. If vulnerabilities are found (i.e., the audit does not 'pass'), the command exits with a non-zero status code (System.stop(1)), making it suitable for CI/CD pipelines.

To run the audit, you can provide options to specify the project path, the output format, and lists of advisories or packages to ignore.

# Example conceptual usage via Mix
mix deps.audit

# The command will exit with status 1 if vulnerabilities are found.

To scan your project's Mix dependencies for security vulnerabilities, execute the deps.audit task using Mix. The task will exit with status 0 if no vulnerabilities are found, or status 1 if vulnerabilities are detected.

$ mix deps.audit

The mix deps.audit task accepts the following options to customize the security scan and report generation:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `--path` | String | _Current directory_ | The root path of the project to audit |
| `--format` | String | `"human"` | The format of the report to generate (`"json"` or `"human"`) |
| `--ignore-advisory-ids` | String | `""` | Comma-separated list of advisory IDs to ignore |
| `--ignore-package-names` | String | `""` | Comma-separated list of package names to ignore |
| `--ignore-file` | String | `""` | Path of the ignore file |

The MixAudit.Audit.report/2 function is the core engine for identifying security vulnerabilities. It takes a list of project dependencies and a map of security advisories, then returns a %MixAudit.Report{} struct.

If any vulnerabilities are found, the pass field in the returned report will be false. Otherwise, it will be true.

# Example usage of the report generation logic
# dependencies: list of %MixAudit.Dependency{} structs
# advisories: Map where keys are package names and values are lists of %MixAudit.Advisory{} structs

MixAudit.Audit.report(dependencies, advisories)
# Returns: %MixAudit.Report{vulnerabilities: [...], pass: boolean}

The MixAudit.Formatting module provides a way to transform audit reports into different output formats. You can use the format/2 function to specify whether you want a human readable output or a json structured output. If an unsupported format is provided, it defaults to MixAudit.Formatting.Human.

# Example usage of the format function
MixAudit.Formatting.format(report, "json")
MixAudit.Formatting.format(report, "human")

The MixAudit.Project.dependencies/1 function retrieves a list of all dependencies found in a Mix project's lockfiles. It scans the root mix.lock and any mix.lock files located within apps/**/ (supporting umbrella projects). Each dependency is returned as a %MixAudit.Dependency{} struct containing the package name, version, and the path to the lockfile it was found in.

MixAudit.Project.dependencies("path/to/your/project")

When calling MixAudit.Formatting.format/2, you can choose from the following format keys:

• "human": Uses MixAudit.Formatting.Human for a human-readable report.
• "json": Uses MixAudit.Formatting.JSON for a machine-readable JSON report.

If a key is not recognized, the system defaults to the human format.

# Available format keys
@formats %{
  "human" => MixAudit.Formatting.Human,
  "json" => MixAudit.Formatting.JSON
}

When running mix deps.audit, you can use the following flags to customize the audit process and report generation: