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
POSTsigned 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.