How Context-Aware Protection Works

shellfirm does not treat every command invocation equally. Before evaluating a command, it inspects your runtime environment for signals that indicate elevated risk. These context signals directly influence the challenge difficulty and the computed risk level, so the same command can require a simple math problem on a feature branch but demand explicit "yes" confirmation on a production server.

Context detection flow

When you run a command, shellfirm performs context detection in the following order:

SSH session -- checks for SSH_CONNECTION or SSH_TTY environment variables
Root user -- checks whether EUID equals 0
Git branch -- runs git rev-parse --abbrev-ref HEAD to get the current branch
Kubernetes context -- runs kubectl config current-context to read the active cluster
Environment variables -- checks NODE_ENV, RAILS_ENV, ENVIRONMENT, and any custom-configured variables for production values
Risk level computation -- aggregates all detected signals into a single risk level

Signal reference

Signal	Detection method	Risk level	Default effect
SSH session	`SSH_CONNECTION` or `SSH_TTY` env var present	Elevated	Challenge escalated to Enter
Root user (uid 0)	`EUID=0` env var	Critical	Challenge escalated to Yes
Protected git branch	`git rev-parse --abbrev-ref HEAD` matches `main`, `master`, `production`, or `release/*`	Critical	Challenge escalated to Yes
Production k8s context	`kubectl config current-context` contains `prod`, `production`, `prd`, or `live`	Critical	Challenge escalated to Yes
`NODE_ENV=production`	Environment variable check	Critical	Challenge escalated to Yes
`RAILS_ENV=production`	Environment variable check	Critical	Challenge escalated to Yes
`ENVIRONMENT=production`	Environment variable check	Critical	Challenge escalated to Yes
Custom env vars	Configured in `settings.yaml` under `context.production_env_vars`	Critical	Challenge escalated to Yes

Risk levels

shellfirm computes one of three risk levels from the detected signals:

Normal -- no risk signals detected. Challenges use the default type configured in your settings.
Elevated -- moderate signals detected (SSH session). Challenges are escalated to at least Enter.
Critical -- high-risk signals detected (root user, protected branch, production k8s context, production env vars). Challenges are escalated to at least Yes.

Context labels

Each detected signal produces a human-readable label that appears in the challenge banner:

Context Labels

ssh=true

root=true

branch=main

k8s=prod-us-east-1

These labels help you understand why shellfirm is being more cautious.

Configuration

All context detection is configurable in ~/.shellfirm/settings.yaml under the context key:

context:
  protected_branches:
    - main
    - master
    - production
    - "release/*"
  production_k8s_patterns:
    - prod
    - production
    - prd
    - live
  production_env_vars:
    NODE_ENV: production
    RAILS_ENV: production
    ENVIRONMENT: production
  escalation:
    elevated: Enter
    critical: Yes

Context detection is one of several escalation layers. Severity-based escalation, group/check-id overrides, and project policies also contribute. See Escalation Logic for the complete pipeline.

See individual pages in this section for detailed configuration of each signal type.