Context-Aware Protection

shellfirm does not treat every command the same way. It detects runtime signals from your environment -- SSH sessions, root access, git branches, Kubernetes contexts, and environment variables -- and automatically escalates protection when the risk is higher.

Risk levels

shellfirm computes a risk level from your environment context:

Risk level	Meaning	Challenge escalation
Normal	No special signals detected	Your configured default
Elevated	Moderate risk signals (SSH session)	At least Enter
Critical	High-risk signals (root, production branch, production k8s, production env)	At least Yes

Detection signals

SSH session

Detected via the SSH_CONNECTION or SSH_TTY environment variables.

When you are connected via SSH, accidental commands have higher impact because you are likely operating on a remote server rather than your local machine.

Risk level: Elevated

Root user

Detected via EUID=0.

Running as root means commands execute without permission checks and can affect the entire system.

Risk level: Critical

Protected git branches

Detected by running git rev-parse --abbrev-ref HEAD and matching against a list of protected branch patterns.

Default protected branches:

• main
• master
• production
• release/* (wildcard -- matches release/v1.0, release/hotfix, etc.)

Risk level: Critical

Configure your own protected branches:

# In ~/.config/shellfirm/settings.yaml
context:
  protected_branches:
    - main
    - master
    - production
    - "release/*"
    - develop

Production Kubernetes context

Detected by running kubectl config current-context and checking if the context name contains any production pattern (case-insensitive).

Default production k8s patterns:

• prod
• production
• prd
• live

Risk level: Critical

A context like prod-us-east-1 or my-company-production would match.

context:
  production_k8s_patterns:
    - prod
    - production
    - prd
    - live
    - my-company-prod

Production environment variables

Detected by checking environment variables against expected values.

Default production env vars:

Variable	Expected value
NODE_ENV	production
RAILS_ENV	production
ENVIRONMENT	production

Risk level: Critical

context:
  production_env_vars:
    NODE_ENV: production
    RAILS_ENV: production
    ENVIRONMENT: production
    FLASK_ENV: production

Challenge escalation

When a risk signal is detected, the challenge type is escalated. The rule is simple: escalation can only make things stricter, never weaker.

effective_challenge = max(configured_challenge, context_minimum)

Escalation defaults

Risk level	Default minimum challenge
Normal	(no escalation)
Elevated	Enter
Critical	Yes

Configuration

context:
  escalation:
    elevated: Enter    # default
    critical: Yes      # default

Examples

Scenario	Default challenge	Context	Effective challenge
Local development	Math	Normal	Math
SSH to staging	Math	Elevated	Enter
On main branch	Math	Critical	Yes
Root user	Enter	Critical	Yes
Already using Yes	Yes	Elevated	Yes (cannot weaken)

Context labels

When context is detected, labels are shown in the challenge prompt:

  ============ RISKY COMMAND DETECTED ============
  Severity: CRITICAL
  Context: ssh=true, branch=main, k8s=prod-us-east-1

  ? Type `yes` to continue Esc to cancel ›

Labels are also included in audit logs for compliance tracking.

Context in project policies

Project policies (.shellfirm.yaml) can define additional context settings that are merged with your global configuration:

version: 1
context:
  protected_branches:
    - main
    - master
    - develop
    - "release/*"
  production_k8s_patterns:
    - prod
    - production

See Team Policies for more details.