use cautious language in security assessments to reduce legal risk and be fair to package authors (#29)

* use cautious language in security assessments to reduce legal risk and be fair to package authors

* fix: format code to pass CI check

* simplify project overview in AGENTS.md

Rewrote the overview to be direct and factual. Removed architecture
diagram and key files sections. Clarified that packages are pre-scanned
so there's no slowdown at install time.

Author: alanzabihi

.gitignore

@@ -25,5 +25,5 @@ Cargo.lock
 # Logs
 *.log
 
-AGENTS.md
+# Generated docs (in .sus-docs/, not root)
 CLAUDE.md

AGENTS.md

@@ -0,0 +1,58 @@
+# sus — Agent Instructions
+
+## Project Overview
+
+sus is a secure package gateway for agents. It wraps npm/yarn/pnpm/bun. Before installing any package, it checks a database of pre-scanned results (CVE lookups, static analysis, threat detection). No scanning happens at install time, so there's no slowdown. If the package passes, sus hands off to your actual package manager.
+
+## Legal & Communication Guidelines
+
+Apply to ALL security assessments, reports, marketing copy, SKILL.md generation, and public-facing content.
+
+### CVE/GHSA Data (from OSV, GitHub Advisory, NVD)
+
+Authoritative third-party data. State as fact.
+- Include CVE/GHSA ID for traceability
+- Cite source: "per GitHub Advisory GHSA-xxxx" or "CVE-2024-xxxxx (OSV)"
+- OK: "lodash 4.17.20 has CVE-2021-23337 (GitHub Advisory)"
+
+### sus-Detected Issues (agentic threats, capability analysis)
+
+Automated assessment. Use cautious language.
+- USE: "detected," "patterns consistent with," "risk indicators," "flagged," "assessed as"
+- AVOID: "vulnerability," "malicious," "dangerous," "compromised," "contains"
+- Include confidence scores when available
+- Frame as input to human judgment, not verdict
+
+### Risk Levels
+
+- "assessed as high-risk" not "is high-risk"
+- "indicators suggest" not "package does X"
+- Never imply maintainer negligence or malice
+
+### Required Context
+
+Imply or include:
+- Assessments are automated, may contain errors
+- Findings are risk indicators, not confirmed threats
+- Point-in-time assessment; security posture changes
+- Dispute process exists for maintainers
+
+### Examples
+
+BAD: "contains malicious code that steals data"
+GOOD: "detected patterns consistent with data exfiltration"
+
+BAD: "dangerous, should never be used"
+GOOD: "assessed as high-risk due to [indicators]; review flagged concerns"
+
+BAD: "maintainer included a backdoor"
+GOOD: "detected code patterns warranting manual review; reported to maintainer"
+
+BAD: "has prompt injection vulnerability"
+GOOD: "flagged for potential prompt injection patterns (confidence: 0.82)"
+
+### Default Behavior
+
+- Understate rather than overstate severity
+- Err toward caution on language
+- False positive published confidently causes more harm than true positive published cautiously

crates/worker/src/scanner/agentic.rs

@@ -216,6 +216,15 @@ Scan this package for security threats. Analyze all files for both **agentic thr
 - **medium**: Suspicious patterns, could be legitimate but warrants investigation
 - **low**: Informational, minor issues, potential false positive
 
+## Output Language (IMPORTANT)
+
+Use cautious, legally defensible language. These are automated assessments, not confirmed verdicts.
+
+- USE: "detected patterns consistent with," "indicators suggest," "flagged for," "code patterns resembling"
+- AVOID: "vulnerability," "malicious," "dangerous," "attack," "exploit," "compromised"
+- Never imply maintainer negligence or malice
+- Frame findings as risk indicators for human review, not definitive judgments
+
 ## Output
 
 Return ONLY valid JSON. Use EXACTLY one of these threat_type values (snake_case):
@@ -234,14 +243,14 @@ Return ONLY valid JSON. Use EXACTLY one of these threat_type values (snake_case)
       "severity": "critical|high|medium|low",
       "confidence": 0.0-1.0,
       "location": "file/path:line",
-      "description": "what it does and why it's suspicious",
+      "description": "detected patterns consistent with [threat]; [specific observation]",
       "snippet": "relevant code (max 100 chars)"
     }
   ],
-  "summary": "brief overall assessment"
+  "summary": "brief overall assessment using cautious language"
 }
 
-If no threats: {"threats": [], "summary": "No threats detected"}"#;
+If no threats: {"threats": [], "summary": "No security concerns detected"}"#;
 
         let output = self.run_opencode(package_dir, prompt).await?;
 
@@ -449,6 +458,15 @@ Downgrade if:
 - Low impact even if exploited
 - Common pattern with known safe usage
 
+## Output Language (IMPORTANT)
+
+Use cautious, legally defensible language. These are automated assessments, not confirmed verdicts.
+
+- USE: "detected patterns consistent with," "indicators suggest," "flagged for," "code patterns resembling"
+- AVOID: "vulnerability," "malicious," "dangerous," "attack," "exploit," "compromised"
+- Never imply maintainer negligence or malice
+- Frame findings as risk indicators for human review, not definitive judgments
+
 ## Output
 
 Return ONLY verified threats. Use EXACTLY one of these threat_type values (snake_case):
@@ -467,14 +485,14 @@ Return ONLY verified threats. Use EXACTLY one of these threat_type values (snake
       "severity": "critical|high|medium|low",
       "confidence": 0.0-1.0,
       "location": "file/path:line",
-      "description": "what it does and why it's dangerous",
+      "description": "verified patterns consistent with [threat]; [specific observation]",
       "snippet": "actual code from the file (max 100 chars)"
     }}
   ],
-  "summary": "brief overall assessment"
+  "summary": "brief overall assessment using cautious language"
 }}
 
-If no threats verified: {{"threats": [], "summary": "No threats confirmed"}}"#,
+If no threats verified: {{"threats": [], "summary": "No security concerns confirmed"}}"#,
             threats_json
         );
 

crates/worker/src/scanner/mod.rs

@@ -125,18 +125,18 @@ pub fn calculate_risk(
         }
     }
 
-    // Check agentic threats
+    // Check agentic threats (use cautious language - these are automated assessments)
     for threat in agentic_threats {
         if threat.confidence > 0.8 {
             reasons.push(format!(
-                "{:?} detected ({}% confidence)",
+                "Detected patterns consistent with {:?} ({}% confidence)",
                 threat.threat_type,
                 (threat.confidence * 100.0) as u8
             ));
             max_level = RiskLevel::Critical;
         } else if threat.confidence > 0.5 {
             reasons.push(format!(
-                "Possible {:?} ({}% confidence)",
+                "Flagged for potential {:?} patterns ({}% confidence)",
                 threat.threat_type,
                 (threat.confidence * 100.0) as u8
             ));
@@ -146,24 +146,24 @@ pub fn calculate_risk(
         }
     }
 
-    // Check risky capabilities
+    // Check risky capabilities (factual observations, not judgments)
     if capabilities.native.has_native {
-        reasons.push("Contains native code".to_string());
+        reasons.push("Package includes native code modules".to_string());
         if max_level == RiskLevel::Clean {
             max_level = RiskLevel::Warning;
         }
     }
 
     if capabilities.process.spawns_children {
-        reasons.push("Can spawn child processes".to_string());
+        reasons.push("Package can spawn child processes".to_string());
         if max_level == RiskLevel::Clean {
             max_level = RiskLevel::Warning;
         }
     }
 
     // Low trust score
     if trust_score < 30 {
-        reasons.push(format!("Low trust score ({})", trust_score));
+        reasons.push(format!("Low trust score assessed ({})", trust_score));
         if max_level == RiskLevel::Clean {
             max_level = RiskLevel::Warning;
         }
@@ -853,6 +853,9 @@ mod tests {
         let (level, reasons) = calculate_risk(&[], &threats, &PackageCapabilities::default(), 75);
         assert_eq!(level, RiskLevel::Critical);
         assert!(reasons.iter().any(|r| r.contains("PromptInjection")));
+        assert!(reasons
+            .iter()
+            .any(|r| r.contains("patterns consistent with")));
     }
 
     #[test]
@@ -865,7 +868,7 @@ mod tests {
         }];
         let (level, reasons) = calculate_risk(&[], &threats, &PackageCapabilities::default(), 75);
         assert_eq!(level, RiskLevel::Warning);
-        assert!(reasons.iter().any(|r| r.contains("Possible")));
+        assert!(reasons.iter().any(|r| r.contains("Flagged for potential")));
     }
 
     #[test]
@@ -900,14 +903,18 @@ mod tests {
         capabilities.process.spawns_children = true;
         let (level, reasons) = calculate_risk(&[], &[], &capabilities, 75);
         assert_eq!(level, RiskLevel::Warning);
-        assert!(reasons.iter().any(|r| r.contains("spawn child processes")));
+        assert!(reasons
+            .iter()
+            .any(|r| r.contains("can spawn child processes")));
     }
 
     #[test]
     fn test_risk_low_trust_score() {
         let (level, reasons) = calculate_risk(&[], &[], &PackageCapabilities::default(), 25);
         assert_eq!(level, RiskLevel::Warning);
-        assert!(reasons.iter().any(|r| r.contains("Low trust score")));
+        assert!(reasons
+            .iter()
+            .any(|r| r.contains("Low trust score assessed")));
     }
 
     #[test]