README

OeditusCredo

Custom Credo checks for detecting common Elixir/Phoenix anti-patterns, mistakes, and CWE Top 25 security vulnerabilities.

Overview

OeditusCredo provides 40 comprehensive custom Credo checks that detect common mistakes, risky code, and security vulnerabilities in Elixir and Phoenix projects:

Error Handling Anti-patterns

MissingErrorHandling - Detects {:ok, x} = pattern without error handling
SilentErrorCase - Detects case statements missing error branches
SwallowingException - Detects try/rescue blocks without logging or re-raising

Database & Performance Issues

InefficientFilter - Detects Repo.all followed by Enum filtering
NPlusOneQuery - Detects potential N+1 queries (Enum.map with Repo calls)
MissingPreload - Detects Ecto queries without proper preloading

LiveView & Concurrency Issues

UnmanagedTask - Detects unsupervised Task.async calls
SyncOverAsync - Detects blocking operations in LiveView/GenServer callbacks
MissingHandleAsync - Detects blocking in handle_event without async pattern
MissingThrottle - Detects form inputs without phx-debounce/throttle
InlineJavascript - Detects inline JS handlers instead of phx-* bindings

Readability

UnnecessaryInterpolatingSigil - Detects ~s/~c/~w without interpolation (suggests ~S/~C/~W)

Code Quality & Maintainability

DirectStructUpdate - Detects direct struct updates instead of changesets
CallbackHell - Detects deeply nested case statements (suggests with)
BlockingInPlug - Detects blocking operations in Plug functions
UnsafeMapAccess - Detects bracket access on maps where dot access is safer (requires typle + Elixir >= 1.20)

Refactoring Suggestions

SuggestFSM - Detects imperative status/state management (suggests Finitomata or :gen_statem)
ChangeRiskAntiPatterns - Flags functions with a high CRAP score (both complex and under-tested). Opt-in/disabled by default; requires coverage data (see Change Risk Anti-Patterns (CRAP) score).

Telemetry & Observability

MissingTelemetryInObanWorker - Detects Oban workers without telemetry instrumentation
MissingTelemetryInLiveViewMount - Detects LiveView mount/3 without telemetry events
TelemetryInRecursiveFunction - Detects telemetry inside recursive functions (anti-pattern)
MissingTelemetryInAuthPlug - Detects auth/authz plugs without telemetry
MissingTelemetryForExternalHttp - Detects HTTP client calls without telemetry wrapper

Security - Injection (CWE-89, CWE-78, CWE-94, CWE-79)

SQLInjection - Detects string interpolation/concatenation in Ecto queries
OSCommandInjection - Detects user input passed to System.cmd/os:cmd
CodeInjection - Detects dynamic code execution via Code.eval_string
XSSVulnerability - Detects raw/1 with user input in templates

Security - Authentication & Authorization (CWE-306, CWE-862, CWE-863, CWE-639)

MissingAuthentication - Detects controllers/routers without authentication plugs
MissingAuthorization - Detects Phoenix actions without authorization checks
IncorrectAuthorization - Detects role checks using negation/!= patterns
InsecureDirectObjectReference - Detects direct DB lookups from user params without ownership checks

Security - Data Protection (CWE-200, CWE-798, CWE-502)

SensitiveDataExposure - Detects sensitive fields in JSON responses and inspect output
HardcodedCredentials - Detects hardcoded passwords, API keys, tokens, and secrets
UnsafeDeserialization - Detects :erlang.binary_to_term without the :safe option

Security - Input & File Handling (CWE-20, CWE-22, CWE-434)

ImproperInputValidation - Detects missing validation of external input
PathTraversal - Detects user input in file paths without sanitization
UnrestrictedFileUpload - Detects file uploads without content-type validation

Security - Web (CWE-352, CWE-918)

MissingCSRFProtection - Detects API pipelines without CSRF protection
SSRFVulnerability - Detects HTTP requests with user-controlled URLs

Security - Race Conditions (CWE-367)

TOCTOU - Detects time-of-check/time-of-use patterns (File.exists? then File.read)

Important Note

All these checks are somewhat opinionated and might produce false positives. If a warning does not apply to your specific case, you can suppress it with # credo:disable-for-next-line or any other Credo config comment directive.

Installation

As a Project Dependency

Add oeditus_credo to your list of dependencies in mix.exs:

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

Standalone Installation (No Dependency Required)

You can also use OeditusCredo without adding it to your project dependencies:

# Install as a Hex archive (recommended for development)
mix archive.install hex oeditus_credo

# Or download and use the escript executable (best for CI/CD)
curl -L https://github.com/Oeditus/oeditus_credo/releases/latest/download/oeditus_credo -o oeditus_credo
chmod +x oeditus_credo

See STANDALONE.md for detailed standalone usage instructions.

Usage

With Standalone Installation

If you installed OeditusCredo as an archive or escript:

mix oeditus_credo              # Run with all checks enabled
mix oeditus_credo --strict     # Fail on any issues
mix oeditus_credo lib/my_app   # Analyze specific directory

With Project Dependency

Add the checks to your .credo.exs configuration:

%{
  configs: [
    %{
      name: "default",
      plugins: [],
      requires: [],
      checks: %{
        enabled: [
          # ... existing checks ...
          # Error Handling
          {OeditusCredo.Check.Warning.MissingErrorHandling, []},
          {OeditusCredo.Check.Warning.SilentErrorCase, []},
          {OeditusCredo.Check.Warning.SwallowingException, []},
          # Database & Performance
          {OeditusCredo.Check.Warning.InefficientFilter, []},
          {OeditusCredo.Check.Warning.NPlusOneQuery, []},
          {OeditusCredo.Check.Warning.MissingPreload, []},
          # LiveView & Concurrency
          {OeditusCredo.Check.Warning.UnmanagedTask, []},
          {OeditusCredo.Check.Warning.SyncOverAsync, []},
          {OeditusCredo.Check.Warning.MissingHandleAsync, []},
          {OeditusCredo.Check.Warning.MissingThrottle, []},
          {OeditusCredo.Check.Warning.InlineJavascript, []},
          # Readability
          {OeditusCredo.Check.Readability.UnnecessaryInterpolatingSigil, []},
          # Code Quality
          {OeditusCredo.Check.Warning.DirectStructUpdate, []},
          {OeditusCredo.Check.Warning.CallbackHell, [max_nesting: 2]},
          {OeditusCredo.Check.Warning.BlockingInPlug, []},
          {OeditusCredo.Check.Warning.UnsafeMapAccess, []},
          # Refactoring Suggestions
          {OeditusCredo.Check.Refactoring.SuggestFSM, []},
          # Telemetry & Observability
          {OeditusCredo.Check.Warning.MissingTelemetryInObanWorker, []},
          {OeditusCredo.Check.Warning.MissingTelemetryInLiveViewMount, []},
          {OeditusCredo.Check.Warning.TelemetryInRecursiveFunction, []},
          {OeditusCredo.Check.Warning.MissingTelemetryInAuthPlug, []},
          {OeditusCredo.Check.Warning.MissingTelemetryForExternalHttp, []},
          # Security - Injection
          {OeditusCredo.Check.Security.SQLInjection, []},
          {OeditusCredo.Check.Security.OSCommandInjection, []},
          {OeditusCredo.Check.Security.CodeInjection, []},
          {OeditusCredo.Check.Security.XSSVulnerability, []},
          # Security - Auth
          {OeditusCredo.Check.Security.MissingAuthentication, []},
          {OeditusCredo.Check.Security.MissingAuthorization, []},
          {OeditusCredo.Check.Security.IncorrectAuthorization, []},
          {OeditusCredo.Check.Security.InsecureDirectObjectReference, []},
          # Security - Data Protection
          {OeditusCredo.Check.Security.SensitiveDataExposure, []},
          {OeditusCredo.Check.Security.HardcodedCredentials, []},
          {OeditusCredo.Check.Security.UnsafeDeserialization, []},
          # Security - Input & File Handling
          {OeditusCredo.Check.Security.ImproperInputValidation, []},
          {OeditusCredo.Check.Security.PathTraversal, []},
          {OeditusCredo.Check.Security.UnrestrictedFileUpload, []},
          # Security - Web
          {OeditusCredo.Check.Security.MissingCSRFProtection, []},
          {OeditusCredo.Check.Security.SSRFVulnerability, []},
          # Security - Race Conditions
          {OeditusCredo.Check.Security.TOCTOU, []}
        ]
      }
    ]
  ]
}

Then run:

mix credo

Change Risk Anti-Patterns (CRAP) score

ChangeRiskAntiPatterns is opt-in and disabled by default because it needs test-coverage data that Credo cannot produce on its own. It combines each function's cyclomatic complexity with its test coverage:

CRAP = complexity^2 * (1 - coverage/100)^3 + complexity

A fully covered function scores its complexity; a complex, untested function scores much higher. The default maximum is 30 (the historical CRAP convention).

IMPORTANT: This check only works when run after generating persisted coverage data. It reads cover/default.coverdata, which is produced by --export-coverage:
mix test --cover --export-coverage default
mix credo
Plain mix test --cover prints a coverage report but does not leave an importable coverage file, so it is not sufficient. When no coverage data is found, the check does nothing by default (so it never breaks a mix credo run launched without coverage). Set require_coverage: true to turn missing coverage into a reported issue instead (useful in CI).

Enable it in .credo.exs:

{OeditusCredo.Check.Refactoring.ChangeRiskAntiPatterns, []}

Parameters: max_score (default 30), coverdata (default "cover/default.coverdata"), exclude_test_files (default true), require_coverage (default false).

Configuration Options

All checks support configuration parameters. Pass them in .credo.exs:

General (Credo-standard) Parameters

Every check accepts the following general parameters provided by Credo:

false -- Disable a check entirely. When a check tuple uses false instead of a keyword list, the check is skipped and produces no issues.
```
# Disable a check
{OeditusCredo.Check.Warning.NPlusOneQuery, false}
```
exit_status (integer()) -- Override the exit status contributed by issues from this check. By default, all checks in the :warning category contribute exit status 16. Setting exit_status: 0 means the check still runs and reports issues, but they will not cause a non-zero exit code.
```
# Run the check but don't fail CI on its issues
{OeditusCredo.Check.Warning.NPlusOneQuery, exit_status: 0}

# Custom exit status
{OeditusCredo.Check.Security.SQLInjection, exit_status: 2}
```
priority -- Override the base priority for the check (:low, :normal, :high, :higher, or :ignore).

files -- Restrict which files the check runs on:

{OeditusCredo.Check.Security.SQLInjection, files: %{included: ["lib/my_app/repo.ex"]}}

These parameters can be combined with any check-specific parameters.

Common Check-Specific Parameters

Every OeditusCredo check additionally accepts:

exclude_test_files (boolean(), default: false) -- When set to true, files ending in _test.exs or located under a /test/ directory are skipped.

Code Quality

CallbackHell: max_nesting -- Maximum allowed case nesting depth (default: 2)
DirectStructUpdate: extra_struct_patterns -- Additional regex strings for struct-like variable names (default: [])
BlockingInPlug: extra_blocking_modules -- Additional module atoms to treat as blocking (default: [])

Refactoring Suggestions

SuggestFSM: status_field_names -- Field names to watch (default: [:status, :state]); min_states -- Minimum distinct status values before flagging (default: 3)
ChangeRiskAntiPatterns: max_score -- Maximum CRAP score before a function is reported (default: 30); coverdata -- Path to the persisted coverage file (default: "cover/default.coverdata"); exclude_test_files -- Skip test files (default: true); require_coverage -- Report an issue when coverage data is missing instead of skipping (default: false). See Change Risk Anti-Patterns (CRAP) score for the required workflow.

LiveView & Concurrency

SyncOverAsync: extra_blocking_modules -- Additional blocking module atoms (default: []); callback_functions -- Callback names to check (default: [:handle_event, :handle_call, :handle_info, :handle_cast, :handle_continue])
MissingHandleAsync: extra_blocking_modules -- Additional blocking module atoms (default: [])

Telemetry & Observability

MissingTelemetryForExternalHttp: extra_http_modules -- Additional {module_parts, [functions]} tuples (default: [])
MissingTelemetryInAuthPlug: extra_auth_plug_names -- Additional auth plug name substrings (default: [])

Security -- Injection

CodeInjection: extra_dangerous_functions -- Additional Code.* function atoms to flag (default: [])

Security -- Auth

MissingAuthentication: sensitive_actions -- Controller actions requiring auth (default: [:index, :show, :create, :new, :update, :edit, :delete, :destroy])
MissingAuthorization: extra_auth_indicators -- Additional authorization indicator substrings (default: [])
IncorrectAuthorization: extra_auth_indicators -- Additional authorization indicator substrings (default: [])
InsecureDirectObjectReference: extra_ownership_indicators -- Additional ownership/auth indicator substrings (default: [])

Security -- Data Protection

SensitiveDataExposure: extra_sensitive_terms -- Additional sensitive field substrings (default: [])
HardcodedCredentials: extra_credential_terms -- Additional credential name substrings (default: [])

Security -- Web

SSRFVulnerability: extra_http_modules -- Additional HTTP module atom lists, e.g. [[:MyHTTP]] (default: [])

Example

# Customise check-specific params
{OeditusCredo.Check.Warning.CallbackHell, [max_nesting: 3]},
{OeditusCredo.Check.Warning.SyncOverAsync, [extra_blocking_modules: [:ExternalAPI]]},
{OeditusCredo.Check.Security.CodeInjection, [extra_dangerous_functions: [:compile_string]]},
{OeditusCredo.Check.Security.HardcodedCredentials, [exclude_test_files: true, extra_credential_terms: ["conn_string"]]},
{OeditusCredo.Check.Warning.MissingTelemetryForExternalHttp, [
  extra_http_modules: [{[:MyApp, :HTTP], [:get, :post]}]
]},

# Run check as advisory only (won't affect exit code)
{OeditusCredo.Check.Warning.DirectStructUpdate, exit_status: 0},

# Disable a check entirely
{OeditusCredo.Check.Warning.InlineJavascript, false}

Test Coverage

The library includes comprehensive tests for all 40 checks. Run tests with:

mix test

Run mix test to see the current test count and coverage.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License. See LICENSE for details.

Next Page → Quick Start