Suppressing Rules

Not every finding needs action. Sometimes a pattern that’s generally problematic is fine in your specific context. This guide explains how to suppress rules when they don’t apply.

When to Suppress

Suppress a rule when:

The context makes it safe. An HTTP call to localhost doesn’t need the same timeout as one to an external service.
You have safeguards elsewhere. Maybe retry logic exists at a different layer.
It’s intentional. You’ve considered the trade-off and accepted the risk.
It’s a false positive. The rule doesn’t understand your specific pattern.

Don’t suppress just to make findings go away. Each suppression should have a reason you could explain to a teammate.

Inline Suppression

Suppress a specific finding with a comment on the line above:

response = requests.get(internal_url)  # Internal service, <1ms latency

resp, err := http.Get(internalURL) // Internal service, <1ms latency

let response = client.get(internal_url).send()?; // Internal service

// unfault: ignore[typescript.http.missing_timeout]
const response = await fetch(internalUrl); // Internal service

Multiple Rules

Suppress multiple rules on the same line:

# unfault: ignore[python.http.missing_timeout, python.http.missing_retry]
response = requests.get(cache_url)  # Local cache, fast and reliable

Adding Context

Add a reason after the rule list (recommended):

# unfault: ignore[python.http.missing_timeout] -- localhost cache, sub-ms response
response = requests.get("http://localhost:6379/health")

The text after -- is ignored by Unfault but helps humans understand why the suppression exists.

File-Level Suppression

Suppress rules for an entire file by adding the comment at the top:

# This is a CLI script, not a service. Structured logging doesn't apply.

import click

@click.command()
def main():
    print("Running migration...")

This is useful for:

Scripts that aren’t production services
Test files with intentionally problematic patterns
Generated code

Project-Level Suppression

Suppress rules across your entire project in your manifest file:

[tool.unfault.rules]
exclude = [
    "python.missing_structured_logging",  # We use custom logging
    "python.http.missing_circuit_breaker", # Circuit breakers at gateway
]

[rules]
exclude = [
    "go.missing_structured_logging",
    "go.http.missing_circuit_breaker",
]

[package.metadata.unfault.rules]
exclude = [
    "rust.missing_structured_logging",
    "rust.http.missing_circuit_breaker",
]

{
  "unfault": {
    "rules": {
      "exclude": [
        "typescript.missing_structured_logging",
        "typescript.http.missing_circuit_breaker"
      ]
    }
  }
}

Path-Based Exclusions

Exclude rules for specific paths:

[tool.unfault.rules]
exclude = [
    "python.http.*:scripts/*",           # All HTTP rules in scripts/
    "python.missing_timeout:tests/*",    # Timeouts in tests
]

The pattern is rule:path-glob.

Severity Overrides

Instead of suppressing entirely, you can lower a rule’s severity:

[tool.unfault.rules.severity]
"python.bare_except" = "low"           # Demote to low
"python.http.missing_retry" = "medium" # Demote from high to medium

This keeps the finding visible but changes how it’s prioritized.

Checking Suppressions

To see what’s being suppressed, review your configuration files and inline comments. Suppressions are documented where they’re defined:

Inline: Search for unfault: ignore in your code
File-level: Look for unfault: ignore-file at the top of files
Project-level: Check the exclude array in your pyproject.toml, Cargo.toml, or package.json

Running unfault review --output full shows the rules that matched, making it easier to understand what’s being checked.

Common Suppression Patterns

Internal Services

# unfault: ignore[python.http.missing_timeout] -- internal service mesh, handled by sidecar
response = requests.get(f"http://user-service/users/{user_id}")

Test Code

[tool.unfault.rules]
exclude = [
    "*:tests/*",       # Exclude all rules in tests/
    "*:*_test.py",     # Exclude all rules in test files
]

Generated Code

# unfault: ignore-file[*]
# AUTO-GENERATED FILE - DO NOT EDIT
# Generated by protoc-gen-python

Legacy Code

[tool.unfault.rules]
exclude = [
    "*:legacy/*",  # Legacy code, being migrated
]

Scripts vs Services

[tool.unfault.rules]
exclude = [
    "python.fastapi.*:scripts/*",           # Scripts aren't FastAPI services
    "python.missing_structured_logging:scripts/*", # CLI output, not structured logs
]

Best Practices

Do

Add a reason to inline suppressions
Use the narrowest suppression that works (inline > file > project)
Review project-level suppressions periodically
Use severity overrides instead of full suppression when possible

Don’t

Suppress rules just to get a clean report
Use blanket * suppressions without good reason
Forget why something was suppressed (always add context)
Suppress in production code without team discussion

Suppression vs Configuration

Approach	Use When
Inline suppression	Specific line has valid reason to skip the rule
File suppression	Entire file is different (script, test, generated)
Project exclusion	Rule doesn’t fit your architecture at all
Severity override	Rule applies but isn’t as important for your context
Dimension filter	You want to focus on specific areas