strawberry/src/file_watch.cpp
trvon abe945097e
Monitor execs and file writes on macOS with Endpoint Security
New meson option enable_endpoint_security (auto, macOS only) links
EndpointSecurity and bsm and builds three ES backends behind the
existing interfaces. Helpers are in src/platform/es_support.hpp.

- ProcessMonitor: NOTIFY_EXEC events (pid, parent, path, dev:ino,
  argv, start time) plus NOTIFY_TRACE and NOTIFY_KEXTLOAD for the
  behavior rules. Events go to a bounded queue (4096, overflow counted
  in events_dropped) drained on the monitor thread, so callbacks stay
  on one thread. Without an ES client the monitor polls libproc
  (backend "libproc"). backend_name() reports "endpoint_security".
- ExecGuard: AUTH_EXEC with the fanotify guard's rules. It fails open
  at min(timeout, ES deadline - 500 ms) and on a full queue, and on
  macOS 27+ ES_DEADLINE_MISS_MODE_FAIL_OPEN makes the kernel allow a
  missed deadline too. Platform binaries and SIP paths are never
  denied, and our own execs are muted. ES does not cache verdicts, so
  rule changes apply on the next exec. Our own cache keys on
  dev:ino:size:mtime:generation. The image is opened by path and its
  dev:ino checked against the event; a swapped file counts as
  unscanned.
- FileWatcher: NOTIFY_CREATE/RENAME/CLOSE(modified) with inverted
  target-path muting: named entries selected literally, whole
  directories by prefix. macos_watch_specs() covers launchd
  agents/daemons, periodic jobs, cron tabs, sudo drop-ins, shell rc
  files, authorized_keys, Downloads and the temp directories.
  match_watch_spec() (direct children, as with fanotify directory
  marks) is portable and tested. Home dirs come from the directory
  service (local_home_dirs).

Every ES handler is noexcept and records swallowed exceptions. Client
errors name the missing requirement (root, entitlement, Full Disk
Access), and the daemon keeps running detection-only.

macos_es_live (root, ES entitlement) checks deny/allow/cache/
platform-binary/fail-open/audit for the guard, exec telemetry and
the file watcher, using small signed payload binaries. It has not run
yet: the development Mac has SIP enabled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 09:55:21 -06:00

491 lines
19 KiB
C++

#include "strawberry/file_watch.hpp"
#include "strawberry/parse_num.hpp"
#include "strawberry/thread_entry.hpp"
#include <algorithm>
#include <atomic>
#include <chrono>
#include <cstring>
#include <filesystem>
#include <iostream>
#include <map>
#include <sstream>
#include <thread>
#include <fcntl.h>
#include <poll.h>
#if defined(__linux__)
#include <sys/fanotify.h>
#endif
#include <unistd.h>
#if defined(__APPLE__)
#include <pwd.h>
#endif
#if defined(__APPLE__) && STRAWBERRY_HAVE_ENDPOINT_SECURITY
#include "platform/es_support.hpp"
#include "strawberry/swallowed.hpp"
#endif
namespace strawberry {
namespace fs = std::filesystem;
std::vector<WatchSpec> default_watch_specs(const std::vector<std::string>& home_dirs) {
std::vector<WatchSpec> specs{
{"/etc/systemd/system", "persistence", "systemd unit", {}, true},
{"/etc/systemd/user", "persistence", "systemd user unit", {}, true},
{"/usr/lib/systemd/system", "persistence", "systemd unit", {}, true},
{"/etc/cron.d", "persistence", "cron job", {}, true},
{"/etc/cron.hourly", "persistence", "cron job", {}, true},
{"/etc/cron.daily", "persistence", "cron job", {}, true},
{"/etc/cron.weekly", "persistence", "cron job", {}, true},
{"/etc/cron.monthly", "persistence", "cron job", {}, true},
{"/var/spool/cron", "persistence", "user crontab", {}, true},
{"/var/spool/cron/crontabs", "persistence", "user crontab", {}, true},
{"/etc/profile.d", "persistence", "login script", {}, true},
{"/etc/sudoers.d", "persistence", "sudoers", {}, true},
{"/etc/xdg/autostart", "persistence", "desktop autostart", {}, true},
{"/etc/udev/rules.d", "persistence", "udev rule", {}, true},
{"/etc", "persistence", "system startup file",
{"ld.so.preload", "crontab", "sudoers", "rc.local", "profile", "bash.bashrc", "zshrc", "environment"}, true},
{"/tmp", "drop", "temporary directory", {}, true},
{"/var/tmp", "drop", "temporary directory", {}, true},
{"/dev/shm", "drop", "shared memory", {}, true},
};
for (const auto& home : home_dirs) {
specs.push_back({home + "/.config/systemd/user", "persistence", "systemd user unit", {}, false});
specs.push_back({home + "/.config/autostart", "persistence", "desktop autostart", {}, false});
specs.push_back({home + "/.ssh", "persistence", "ssh authorized_keys", {"authorized_keys", "authorized_keys2", "rc"}, false});
specs.push_back({home, "persistence", "shell rc file",
{".bashrc", ".bash_profile", ".bash_login", ".profile", ".zshrc", ".zprofile", ".zshenv",
".xprofile", ".xinitrc"}, false});
specs.push_back({home + "/Downloads", "drop", "downloads", {}, false});
}
return specs;
}
std::vector<WatchSpec> macos_watch_specs(const std::vector<std::string>& home_dirs) {
std::vector<WatchSpec> specs{
{"/Library/LaunchDaemons", "persistence", "launch daemon", {}, true},
{"/Library/LaunchAgents", "persistence", "launch agent", {}, true},
{"/Library/StartupItems", "persistence", "startup item", {}, true},
{"/Library/Security/SecurityAgentPlugins", "persistence", "authorization plugin", {}, true},
{"/private/etc/periodic/daily", "persistence", "periodic job", {}, true},
{"/private/etc/periodic/weekly", "persistence", "periodic job", {}, true},
{"/private/etc/periodic/monthly", "persistence", "periodic job", {}, true},
{"/private/var/at/tabs", "persistence", "user crontab", {}, true},
{"/usr/lib/cron/tabs", "persistence", "user crontab", {}, true},
{"/private/etc/sudoers.d", "persistence", "sudoers", {}, true},
{"/private/etc", "persistence", "system startup file",
{"sudoers", "profile", "zshrc", "zprofile", "bashrc", "rc.common", "launchd.conf", "crontab", "periodic.conf"},
true},
{"/private/tmp", "drop", "temporary directory", {}, true},
{"/private/var/tmp", "drop", "temporary directory", {}, true},
{"/Users/Shared", "drop", "shared folder", {}, true},
};
for (const auto& home : home_dirs) {
specs.push_back({home + "/Library/LaunchAgents", "persistence", "launch agent", {}, false});
specs.push_back({home + "/.ssh", "persistence", "ssh authorized_keys", {"authorized_keys", "authorized_keys2", "rc"}, false});
specs.push_back({home, "persistence", "shell rc file",
{".bashrc", ".bash_profile", ".bash_login", ".profile", ".zshrc", ".zprofile", ".zshenv",
".zlogin"}, false});
specs.push_back({home + "/Downloads", "drop", "downloads", {}, false});
}
return specs;
}
std::vector<WatchSpec> platform_watch_specs(const std::vector<std::string>& home_dirs) {
#if defined(__APPLE__)
return macos_watch_specs(home_dirs);
#else
return default_watch_specs(home_dirs);
#endif
}
const WatchSpec* match_watch_spec(const std::vector<WatchSpec>& specs, const std::string& path) {
const auto slash = path.rfind('/');
if (slash == std::string::npos || slash + 1 >= path.size()) {
return nullptr;
}
const std::string dir = slash == 0 ? std::string("/") : path.substr(0, slash);
const std::string name = path.substr(slash + 1);
for (const auto& spec : specs) {
if (spec.dir != dir) {
continue;
}
if (spec.names.empty() || std::find(spec.names.begin(), spec.names.end(), name) != spec.names.end()) {
return &spec;
}
}
return nullptr;
}
#if defined(__APPLE__)
std::vector<std::string> local_home_dirs() {
std::vector<std::string> homes{"/var/root"};
::setpwent();
while (const passwd* entry = ::getpwent()) {
if (entry->pw_uid >= 501 && entry->pw_uid < 60000 && entry->pw_dir != nullptr
&& std::string_view(entry->pw_dir).starts_with("/Users/")) {
homes.emplace_back(entry->pw_dir);
}
}
::endpwent();
std::sort(homes.begin() + 1, homes.end());
homes.erase(std::unique(homes.begin(), homes.end()), homes.end());
return homes;
}
#endif
std::vector<std::string> home_dirs_from_passwd(const std::string& passwd_text) {
std::vector<std::string> homes{"/root"};
std::istringstream input(passwd_text);
std::string line;
while (std::getline(input, line)) {
std::vector<std::string> fields;
std::stringstream ss(line);
std::string field;
while (std::getline(ss, field, ':')) {
fields.push_back(field);
}
if (fields.size() < 7) {
continue;
}
{
const int uid = parse_number<int>(fields[2]).value_or(-1);
if (uid >= 1000 && uid < 60000 && fields[5].starts_with("/home/")) {
homes.push_back(fields[5]);
}
}
}
return homes;
}
#if defined(__linux__)
class FileWatcher::Impl {
public:
~Impl() { stop(); }
bool start(std::vector<WatchSpec> specs, std::function<void(const FileWriteEvent&)> on_event) {
stop();
on_event_ = std::move(on_event);
fan_fd_ = ::fanotify_init(FAN_CLASS_NOTIF | FAN_CLOEXEC | FAN_NONBLOCK | FAN_REPORT_DFID_NAME,
O_RDONLY | O_CLOEXEC | O_LARGEFILE);
if (fan_fd_ < 0) {
error_ = std::string("fanotify_init (DFID_NAME) failed: ") + std::strerror(errno);
return false;
}
for (auto& spec : specs) {
std::error_code ec;
if (!fs::is_directory(spec.dir, ec)) {
continue;
}
const auto key = handle_key(spec.dir);
if (key.empty()) {
continue;
}
const uint64_t mask = FAN_CREATE | FAN_MOVED_TO | FAN_CLOSE_WRITE | FAN_EVENT_ON_CHILD;
if (::fanotify_mark(fan_fd_, FAN_MARK_ADD, mask, AT_FDCWD, spec.dir.c_str()) != 0) {
continue;
}
specs_by_handle_.emplace(key, std::move(spec));
}
if (specs_by_handle_.empty()) {
error_ = "no watch directories could be marked";
::close(fan_fd_);
fan_fd_ = -1;
return false;
}
running_ = true;
thread_ = std::thread(run_guarded("file-watch", [this]() { loop(); }));
std::cout << "[FileWatcher] Watching " << specs_by_handle_.size() << " persistence/drop location(s)" << std::endl;
return true;
}
void stop() {
if (running_.exchange(false) && thread_.joinable()) {
thread_.join();
}
if (fan_fd_ >= 0) {
::close(fan_fd_);
fan_fd_ = -1;
}
specs_by_handle_.clear();
}
bool active() const { return running_; }
std::size_t watched() const { return specs_by_handle_.size(); }
const std::string& error() const { return error_; }
private:
// Directory identity: handle type + opaque handle bytes.
static std::string handle_key(const std::string& dir) {
struct {
file_handle handle;
unsigned char bytes[MAX_HANDLE_SZ];
} buffer{};
buffer.handle.handle_bytes = MAX_HANDLE_SZ;
int mount_id = 0;
if (::name_to_handle_at(AT_FDCWD, dir.c_str(), &buffer.handle, &mount_id, 0) != 0) {
return {};
}
return std::to_string(buffer.handle.handle_type) + ":"
+ std::string(reinterpret_cast<const char*>(buffer.handle.f_handle), buffer.handle.handle_bytes);
}
void loop() {
alignas(fanotify_event_metadata) char buffer[16384];
while (running_) {
pollfd pfd{fan_fd_, POLLIN, 0};
if (::poll(&pfd, 1, 200) <= 0 || (pfd.revents & POLLIN) == 0) {
continue;
}
const ssize_t length = ::read(fan_fd_, buffer, sizeof(buffer));
if (length <= 0) {
continue;
}
auto* metadata = reinterpret_cast<fanotify_event_metadata*>(buffer);
ssize_t remaining = length;
while (FAN_EVENT_OK(metadata, remaining)) {
handle(metadata);
metadata = FAN_EVENT_NEXT(metadata, remaining);
}
}
}
void handle(const fanotify_event_metadata* metadata) {
if (metadata->vers != FANOTIFY_METADATA_VERSION || (metadata->mask & FAN_ONDIR) != 0) {
return;
}
auto* info = reinterpret_cast<const fanotify_event_info_fid*>(metadata + 1);
if (info->hdr.info_type != FAN_EVENT_INFO_TYPE_DFID_NAME) {
return;
}
const auto* handle = reinterpret_cast<const file_handle*>(info->handle);
const std::string key = std::to_string(handle->handle_type) + ":"
+ std::string(reinterpret_cast<const char*>(handle->f_handle), handle->handle_bytes);
const char* name = reinterpret_cast<const char*>(handle->f_handle) + handle->handle_bytes;
const auto it = specs_by_handle_.find(key);
if (it == specs_by_handle_.end() || name == nullptr || name[0] == '\0') {
return;
}
const auto& spec = it->second;
const std::string entry(name);
if (!spec.names.empty() && std::find(spec.names.begin(), spec.names.end(), entry) == spec.names.end()) {
return;
}
// Drop dirs: only completed writes matter (executables written there).
if (spec.category == "drop" && (metadata->mask & (FAN_CLOSE_WRITE | FAN_MOVED_TO)) == 0) {
return;
}
FileWriteEvent event;
event.pid = metadata->pid;
event.path = spec.dir + "/" + entry;
event.category = spec.category;
event.label = spec.label;
event.system_scope = spec.system_scope;
event.timestamp_ns = static_cast<uint64_t>(std::chrono::duration_cast<std::chrono::nanoseconds>(
std::chrono::system_clock::now().time_since_epoch()).count());
if (on_event_) {
try {
on_event_(event);
} catch (const std::exception& e) {
std::cerr << "[FileWatcher] handler failed: " << e.what() << std::endl;
}
}
}
int fan_fd_ = -1;
std::atomic<bool> running_{false};
std::thread thread_;
std::map<std::string, WatchSpec> specs_by_handle_;
std::function<void(const FileWriteEvent&)> on_event_;
std::string error_;
};
#elif defined(__APPLE__) && STRAWBERRY_HAVE_ENDPOINT_SECURITY
// macOS: Endpoint Security notify events. Target-path muting is inverted, so
// only events under the watched locations reach the handler: named entries
// are selected literally, whole directories by prefix.
class FileWatcher::Impl {
public:
~Impl() { stop(); }
bool start(std::vector<WatchSpec> specs, std::function<void(const FileWriteEvent&)> on_event) {
stop();
on_event_ = std::move(on_event);
error_.clear();
specs_.clear();
for (auto& spec : specs) {
// ES reports real paths (/etc is /private/etc).
std::error_code ec;
const auto real = fs::weakly_canonical(spec.dir, ec);
if (!ec && !real.empty()) {
spec.dir = real.string();
}
while (spec.dir.size() > 1 && spec.dir.back() == '/') {
spec.dir.pop_back();
}
specs_.push_back(std::move(spec));
}
const auto result = client_.create(^(es_client_t*, const es_message_t* message) { handle(message); });
if (result != ES_NEW_CLIENT_RESULT_SUCCESS) {
error_ = std::string("Endpoint Security client failed: ") + es::new_client_error(result);
return false;
}
es_client_t* client = client_.get();
(void) ::es_unmute_all_target_paths(client);
if (::es_invert_muting(client, ES_MUTE_INVERSION_TYPE_TARGET_PATH) != ES_RETURN_SUCCESS) {
error_ = "es_invert_muting(TARGET_PATH) failed";
client_.reset();
return false;
}
std::size_t selected = 0;
for (const auto& spec : specs_) {
const std::string base = spec.dir == "/" ? std::string("/") : spec.dir + "/";
if (spec.names.empty()) {
selected += ::es_mute_path(client, base.c_str(), ES_MUTE_PATH_TYPE_TARGET_PREFIX) == ES_RETURN_SUCCESS;
continue;
}
bool any = false;
for (const auto& name : spec.names) {
any |= ::es_mute_path(client, (base + name).c_str(), ES_MUTE_PATH_TYPE_TARGET_LITERAL) == ES_RETURN_SUCCESS;
}
selected += any;
}
const es_event_type_t events[] = {ES_EVENT_TYPE_NOTIFY_CREATE, ES_EVENT_TYPE_NOTIFY_RENAME,
ES_EVENT_TYPE_NOTIFY_CLOSE};
if (::es_subscribe(client, events, 3) != ES_RETURN_SUCCESS) {
error_ = "es_subscribe(CREATE/RENAME/CLOSE) failed";
client_.reset();
return false;
}
watched_ = selected;
active_ = true;
std::cout << "[FileWatcher] Watching " << selected << " location(s) (Endpoint Security)" << std::endl;
return true;
}
void stop() {
active_ = false;
client_.reset(); // waits for in-flight handlers
}
bool active() const { return active_; }
std::size_t watched() const { return watched_; }
const std::string& error() const { return error_; }
private:
static std::string destination_path(es_destination_type_t type, const es_file_t* existing, const es_file_t* dir,
const es_string_token_t& filename) {
if (type == ES_DESTINATION_TYPE_EXISTING_FILE) {
return es::file_path(existing);
}
return es::file_path(dir) + "/" + es::to_string(filename);
}
// Runs on the ES queue: never throws.
void handle(const es_message_t* message) noexcept {
try {
std::string path;
bool completed = false; // content is in place (closed after writing, or renamed in)
switch (message->event_type) {
case ES_EVENT_TYPE_NOTIFY_CREATE: {
const auto& e = message->event.create;
path = destination_path(e.destination_type, e.destination.existing_file, e.destination.new_path.dir,
e.destination.new_path.filename);
break;
}
case ES_EVENT_TYPE_NOTIFY_RENAME: {
const auto& e = message->event.rename;
path = destination_path(e.destination_type, e.destination.existing_file, e.destination.new_path.dir,
e.destination.new_path.filename);
completed = true;
break;
}
case ES_EVENT_TYPE_NOTIFY_CLOSE:
if (!message->event.close.modified) {
return;
}
path = es::file_path(message->event.close.target);
completed = true;
break;
default:
return;
}
const WatchSpec* spec = match_watch_spec(specs_, path);
if (spec == nullptr) {
return;
}
// Drop dirs: only completed writes matter (executables written there).
if (spec->category == "drop" && !completed) {
return;
}
FileWriteEvent event;
event.pid = es::pid_of(message->process);
event.path = path;
event.category = spec->category;
event.label = spec->label;
event.system_scope = spec->system_scope;
event.timestamp_ns = es::message_wall_ns(message);
if (on_event_) {
on_event_(event);
}
} catch (const std::exception& e) {
std::cerr << "[FileWatcher] handler failed: " << e.what() << std::endl;
} catch (...) {
STRAWBERRY_NOTE_SWALLOWED();
}
}
es::Client client_;
std::vector<WatchSpec> specs_;
std::function<void(const FileWriteEvent&)> on_event_;
std::atomic<bool> active_{false};
std::size_t watched_ = 0;
std::string error_;
};
#else
// fanotify is Linux-only: report the watcher unavailable.
class FileWatcher::Impl {
public:
bool start(std::vector<WatchSpec> /*specs*/, std::function<void(const FileWriteEvent&)> /*on_event*/) {
error_ = "file watching is not available on this platform";
return false;
}
void stop() {}
bool active() const { return false; }
std::size_t watched() const { return 0; }
const std::string& error() const { return error_; }
private:
std::string error_;
};
#endif
FileWatcher::FileWatcher() : impl_(std::make_unique<Impl>()) {}
FileWatcher::~FileWatcher() = default;
bool FileWatcher::start(std::vector<WatchSpec> specs, std::function<void(const FileWriteEvent&)> on_event) {
return impl_->start(std::move(specs), std::move(on_event));
}
void FileWatcher::stop() {
impl_->stop();
}
bool FileWatcher::active() const {
return impl_->active();
}
std::size_t FileWatcher::watched() const {
return impl_->watched();
}
const std::string& FileWatcher::error() const {
return impl_->error();
}
} // namespace strawberry