Skip to main content

codewhale_runtime/
audit.rs

1//! Lightweight audit logging for sensitive operations.
2
3use std::fs;
4use std::path::{Path, PathBuf};
5
6use chrono::Utc;
7use serde_json::{Value, json};
8
9use crate::private_log::{flush_and_sync, open_append};
10
11/// Append an audit event to `$CODEWHALE_HOME/audit.log` (or the default
12/// `~/.codewhale/audit.log` when no explicit CodeWhale home is configured).
13///
14/// This helper is best-effort by design: callers should not fail critical flows
15/// if audit persistence fails.
16pub fn log_sensitive_event(event: &str, details: Value) {
17    let result = default_audit_path().and_then(|path| append_event(&path, event, details));
18    if let Err(err) = result {
19        crate::logging::warn(format!("audit log write failed: {err}"));
20    }
21}
22
23/// Append an audit event to `<codewhale_home>/audit.log` for a caller that
24/// already owns an explicit Codewhale home (for example the DSH integration's
25/// `DshPaths`), so its audit record lands beside the rest of its state rather
26/// than in whatever home the process environment names (#6534).
27pub fn log_sensitive_event_in(codewhale_home: &Path, event: &str, details: Value) {
28    if let Err(err) = append_event(&codewhale_home.join("audit.log"), event, details) {
29        crate::logging::warn(format!("audit log write failed: {err}"));
30    }
31}
32
33/// Size at which `audit.log` is rolled to `audit.log.1`.
34///
35/// The log was append-only with no bound at all: a real `~/.codewhale/audit.log`
36/// had reached 2.6 MB and was still growing, with nothing in the product that
37/// would ever shrink it. Unbounded growth in the user's config directory is not
38/// a viable end state, and neither is silently discarding the record — so one
39/// previous generation is kept, which bounds the pair at ~2× this value while
40/// preserving well over a year of ordinary use.
41const AUDIT_LOG_ROTATE_BYTES: u64 = 16 * 1024 * 1024;
42
43/// Roll `audit.log` to `audit.log.1` once it passes [`AUDIT_LOG_ROTATE_BYTES`].
44///
45/// Exactly one previous generation is kept; the older `.1` is replaced. Rolling
46/// is a rename, so no record is ever rewritten in place and an event is never
47/// lost to a partially-copied file.
48///
49/// Best-effort by the same rule as the rest of this module: if the roll fails
50/// the event is still appended to the existing file. A too-large audit log is a
51/// far better outcome than a dropped audit record.
52fn rotate_if_oversized(path: &std::path::Path) {
53    let oversized = fs::metadata(path).is_ok_and(|meta| meta.len() >= AUDIT_LOG_ROTATE_BYTES);
54    if !oversized {
55        return;
56    }
57    let mut rolled = path.as_os_str().to_owned();
58    rolled.push(".1");
59    let _ = fs::rename(path, std::path::Path::new(&rolled));
60}
61
62fn append_event(path: &Path, event: &str, details: Value) -> anyhow::Result<()> {
63    let path = path.to_path_buf();
64    let parent = path.parent().map(|p| p.to_path_buf());
65    if let Some(ref parent) = parent {
66        fs::create_dir_all(parent)?;
67    }
68    rotate_if_oversized(&path);
69    // Open for append with a BufWriter for buffered I/O, then flush + fsync
70    // after each event so the record is durably on disk.
71    let mut writer = open_append(&path)?;
72    let record = json!({
73        "ts": Utc::now().to_rfc3339(),
74        "event": event,
75        "details": details,
76    });
77    let line = serde_json::to_string(&record)?;
78    use std::io::Write;
79    writeln!(writer, "{line}")?;
80    flush_and_sync(&mut writer)?;
81    Ok(())
82}
83
84fn default_audit_path() -> anyhow::Result<PathBuf> {
85    // A test that has not sealed its own home must never append to the
86    // developer's real ~/.codewhale/audit.log (#6534); it gets a per-process
87    // scratch log instead. An *ambient* CODEWHALE_HOME is not a seal: it names
88    // somebody's real profile just as `~/.codewhale` does.
89    #[cfg(any(test, feature = "test-support"))]
90    if !crate::test_support::home_is_sealed() {
91        return Ok(crate::test_support::isolated_test_state_root().join("audit.log"));
92    }
93    Ok(codewhale_config::codewhale_home()?.join("audit.log"))
94}
95
96/// Where audit events are written, for surfaces that point a person at the
97/// full record (for example `/permissions`). `None` when no Codewhale home
98/// resolves; callers show a placeholder rather than guessing a path.
99#[must_use]
100pub fn audit_log_path() -> Option<PathBuf> {
101    default_audit_path().ok()
102}
103
104#[cfg(test)]
105mod tests {
106    use super::{AUDIT_LOG_ROTATE_BYTES, rotate_if_oversized};
107
108    /// #6534 guard: with no explicit CODEWHALE_HOME, a test process resolves
109    /// the audit log outside the real user home, so no test can append to it.
110    #[test]
111    fn test_process_never_resolves_the_real_home_audit_log() {
112        let _lock = crate::test_support::lock_test_env();
113        let _home = crate::test_support::EnvVarGuard::remove("CODEWHALE_HOME");
114        let path = super::audit_log_path().expect("audit path");
115        let real = codewhale_paths::user_home()
116            .expect("user home")
117            .join(".codewhale")
118            .join("audit.log");
119        assert_ne!(path, real);
120        assert!(
121            path.starts_with(crate::test_support::isolated_test_state_root()),
122            "{}",
123            path.display()
124        );
125    }
126
127    #[test]
128    fn an_explicit_home_receives_its_own_events() {
129        let dir = tempfile::tempdir().expect("tempdir");
130        super::log_sensitive_event_in(dir.path(), "test.event", serde_json::json!({"k": 1}));
131        let log = std::fs::read_to_string(dir.path().join("audit.log")).expect("audit.log");
132        assert!(log.contains("\"event\":\"test.event\""), "{log}");
133    }
134
135    #[test]
136    fn a_small_log_is_left_alone() {
137        let dir = tempfile::TempDir::new().expect("tempdir");
138        let path = dir.path().join("audit.log");
139        std::fs::write(&path, b"{}\n").expect("write");
140        rotate_if_oversized(&path);
141        assert!(path.exists(), "an ordinary log is never rolled");
142        assert!(!dir.path().join("audit.log.1").exists());
143    }
144
145    #[test]
146    fn an_oversized_log_rolls_to_one_previous_generation() {
147        let dir = tempfile::TempDir::new().expect("tempdir");
148        let path = dir.path().join("audit.log");
149        let rolled = dir.path().join("audit.log.1");
150        std::fs::write(&path, vec![b'x'; AUDIT_LOG_ROTATE_BYTES as usize]).expect("write");
151
152        rotate_if_oversized(&path);
153
154        assert!(
155            !path.exists(),
156            "the live log is rolled aside, not truncated"
157        );
158        assert_eq!(
159            std::fs::metadata(&rolled).expect("rolled log").len(),
160            AUDIT_LOG_ROTATE_BYTES,
161            "the previous generation keeps every byte — rolling is a rename"
162        );
163    }
164
165    #[test]
166    fn rolling_twice_keeps_exactly_one_previous_generation() {
167        let dir = tempfile::TempDir::new().expect("tempdir");
168        let path = dir.path().join("audit.log");
169        let rolled = dir.path().join("audit.log.1");
170
171        std::fs::write(&path, vec![b'a'; AUDIT_LOG_ROTATE_BYTES as usize]).expect("first");
172        rotate_if_oversized(&path);
173        std::fs::write(&path, vec![b'b'; AUDIT_LOG_ROTATE_BYTES as usize]).expect("second");
174        rotate_if_oversized(&path);
175
176        let kept = std::fs::read(&rolled).expect("rolled log");
177        assert_eq!(kept.len(), AUDIT_LOG_ROTATE_BYTES as usize);
178        assert_eq!(kept[0], b'b', "the newer generation replaces the older one");
179        assert!(
180            !dir.path().join("audit.log.2").exists(),
181            "generations must not accumulate — that is the bug being fixed"
182        );
183    }
184
185    #[test]
186    fn a_missing_log_is_not_an_error() {
187        let dir = tempfile::TempDir::new().expect("tempdir");
188        rotate_if_oversized(&dir.path().join("audit.log"));
189    }
190}