Security policies

Policies are deterministic rules evaluated against every event. They see only the event's structured fields — categories, program names, paths, hostnames — plus two facts the server holds: whether a repository is marked restricted, and whether an environment is verified production. They never see command text, file contents or output.

The same engine (packages/policy-engine) runs on the server to open findings and inside the collector for advisory and enforce modes.

Built-in policies

Policy Default severity Matches when
Sensitive file access high A tool touches a path such as .env, a private key, cloud credentials, kubeconfig, Terraform state
Destructive commands high (critical in verified production) A command is classified filesystem.destructive or database.destructive
Credential access high A command reads credentials or prints the environment
Remote code execution high Downloaded or decoded content is piped into a shell or interpreter
Privileged commands medium sudo, su, user management, privileged containers
Security configuration changes medium CI workflows, CODEOWNERS, git hooks, permissions, firewall rules, secrets
History rewrite and force push medium Force push, hard reset, git clean -f, branch force-delete
Unusual network destinations low A command refers to a host outside the policy's allowlist
Activity in restricted repositories medium A session starts or changes files in a repository marked restricted
Production operations high Infrastructure or database operations in a verified production environment

Each can be enabled or disabled, given a different severity, and switched between monitor, advisory and enforce (Security → Policies; requires the Security Analyst, Admin or Owner role).

How commands are classified

Commands are classified on the sender. The classifier tokenizes the command (quotes, escapes, operators), splits pipelines and sequences, unwraps sudo, env VAR=…, time, sh -c '…', and classifies each part by program and flags.

That makes it resistant to simple mistakes in both directions: echo 'rm -rf /' and git commit -m 'drop table' are not flagged, while sudo rm -rf /var/lib/app and bash -c 'git push --force' are.

It is not a shell. Anything it cannot see through is marked opaque:

  • eval, source
  • command substitution $(…) and backticks
  • a program name computed at runtime
  • inline code passed to an interpreter (python -c, node -e)
  • content piped into a shell or interpreter

Opaque commands are still classified as far as possible, and findings on them say the classification is best-effort. Tracemason does not claim to understand every shell command.

Findings

A finding contains: severity, the policy that matched, the affected agent / repository / environment, the evidence events, a plain-language explanation built from structured fields, recommended next steps, a status, and optionally an assignee.

Repeats of the same policy and subject within a session increase the finding's occurrence count rather than opening new findings.

Statuses: Open, Investigating, Acknowledged, Resolved, False positive.

Verified production

A sender can declare environment: "production", but a declaration is not proof. Until an Admin, Owner or Security Analyst verifies the environment (Security → Policies → Environments), production policies do not apply and Destructive commands stays at its normal severity.

Custom rules

Available on the Business plan and above. A custom rule matches when all of its conditions match:

Field Tests
tool.name The tool's name
tool.category, command.category Any action category on the event
command.program Programs invoked by a command
command.host Hostnames referenced
file.path Paths touched
agent.name, environment

Operators: equals, glob (infra/**), regex. Regular expressions with nested quantifiers are rejected to avoid pathological patterns.

Alerts

Each new finding of medium severity or higher raises one alert. Alerts appear in the app and, on the Team plan and above, can be sent to:

  • Email — requires SMTP to be configured on the server. If it is not, the delivery is recorded as skipped, not sent.
  • Webhook — a JSON POST signed with HMAC-SHA256:
X-Tracemason-Timestamp: 1794730000
X-Tracemason-Signature: sha256=<hmac of "<timestamp>.<body>" using the channel secret>

Verify the signature and reject old timestamps to prevent replays. Webhook targets must be public HTTPS addresses. Failed deliveries are retried with backoff and their outcome is shown on the finding.

Alerts can be acknowledged or suppressed. Changing a finding's status away from Open acknowledges its alert.

AI-assisted analysis

Planned, not implemented. No event data is sent to any AI provider. When it exists it will be opt-in per organization, applied after redaction, and labelled as analysis rather than fact.