{"id":17278434,"url":"https://github.com/droe/xnumon","last_synced_at":"2025-04-04T08:06:14.058Z","repository":{"id":54599607,"uuid":"137413815","full_name":"droe/xnumon","owner":"droe","description":"monitor macOS for malicious activity","archived":false,"fork":false,"pushed_at":"2025-02-05T13:18:20.000Z","size":610,"stargazers_count":233,"open_issues_count":13,"forks_count":30,"subscribers_count":21,"default_branch":"develop","last_synced_at":"2025-03-28T07:05:36.645Z","etag":null,"topics":["agent","endpoint-security","macos","process-monitoring","security","security-monitoring"],"latest_commit_sha":null,"homepage":"https://www.roe.ch/xnumon","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"osl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/droe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"auditdump.c","citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-14T22:03:31.000Z","updated_at":"2025-03-27T12:03:36.000Z","dependencies_parsed_at":"2022-08-13T21:00:19.173Z","dependency_job_id":null,"html_url":"https://github.com/droe/xnumon","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droe%2Fxnumon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droe%2Fxnumon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droe%2Fxnumon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/droe%2Fxnumon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/droe","download_url":"https://codeload.github.com/droe/xnumon/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142049,"owners_count":20890652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","endpoint-security","macos","process-monitoring","security","security-monitoring"],"created_at":"2024-10-15T09:11:43.706Z","updated_at":"2025-04-04T08:06:14.037Z","avatar_url":"https://github.com/droe.png","language":"C","readme":"# xnumon - monitor macOS for malicious activity\nhttps://www.roe.ch/xnumon\n\n[//]: # (__BUILD_VERSION__)\n\n## Project Status\n\nmacOS no longer supports kernel extensions, and since macOS 11.0, audit(4) has\nbeen deprecated in favour of the Endpoint Security API and Network Extensions.\naudit(4) has been disabled by default in macOS 14.0.\n\nxnumon still works, though without kext, the acquisition of executable images\nis less reliable.\n\nOn macOS 14.0 and later, you need to re-enable audit(4) by copying\n`/etc/security/audit_control.example` to `/etc/security/audit_control`, then\nrunning `launchctl enable system/com.apple.auditd` as root and rebooting.\n\nTo fully support recent macOS, the kernel extension and `audit(4)` code needs\nto be replaced with two new System Extensions using the Endpoint Security API\nand the Network Extension API respectively.  That work has not started and\nthere is no roadmap.  When or if there are any specific plans, this notice will\nbe updated.  Feel free to contact me if you are interested in working on this.\n\n\n## Overview\n\nxnumon is a monitoring agent that produces system activity logs intended to be\nsuitable for monitoring potentially large fleets of macOS systems for malware\nand intrusions.  It aims at providing similar capabilities on macOS that sysmon\nprovides on Windows.\n\nCurrently implemented are the following\n[log events](https://github.com/droe/xnumon/wiki/Event-Schemata):\n\n-   **xnumon-ops[0]** and **xnumon-stats[1]**: for in-band monitoring of agent\n    status and activity metrics.\u0026nbsp;\u003csup\u003e\u0026ast;\u003c/sup\u003e\n-   **image-exec[2]**: a process has replaced its executable image as a result\n    of calling execve(2) or posix_spawn(2).\u0026nbsp;\u003csup\u003e\u0026ast;\u003c/sup\u003e\n-   **process-access[3]**: a process has accessed and possibly manipulated\n    another process using either task_for_pid or\n    ptrace(2).\u0026nbsp;\u003csup\u003e\u0026ast;\u003c/sup\u003e\n-   **launchd-add[4]**: a process has added or modified a launch daemon or\n    launch agent plist.\u0026nbsp;\u003csup\u003e\u0026dagger;\u003c/sup\u003e\n-   **socket-listen[5]**: a process has started listening on a\n    socket.\u0026nbsp;\u003csup\u003e\u0026ast;\u003c/sup\u003e\n-   **socket-accept[6]**: a process has accepted an incoming\n    connection.\u0026nbsp;\u003csup\u003e\u0026ast;\u003c/sup\u003e\n-   **socket-connect[7]**: a process has initiated an outgoing\n    connection.\u0026nbsp;\u003csup\u003e\u0026Dagger;\u003c/sup\u003e\n\n\u003csup\u003e\u0026ast;\u003c/sup\u003e    _stable_  \n\u003csup\u003e\u0026dagger;\u003c/sup\u003e _experimental_  \n\u003csup\u003e\u0026Dagger;\u003c/sup\u003e _stable, but limited to blocking sockets due to an\nunresolved bug in audit(4)_\n\nxnumon provides context information such as executable image hashes, code\nsignature meta-data, script shebang handling, and the history of previous\nexecutable images that led to the current process state.  It does so by\ntracking fork and other syscalls instead of relying only on the ppid, which\ncan change over the lifetime of a process.  For the reliable acquisition of\nimage hashes even from short-living or self-modifying executables, xnumon comes\nwith an optional kernel extension.\n\nxnumon is configurable.  It supports different log formats and hash algorithms.\nIn order to reduce log volume close to the source, xnumon implements a number\nof suppression mechanisms and allows tuning the level of information per event.\nThe log subsystem was designed to be easy to extend with custom log drivers.\n\n\n## Requirements\n\nA supported version of macOS, for full support includingt the kext:\n\n-   macOS 10.14 Mojave\n-   macOS 10.13 High Sierra\n-   macOS 10.12 Sierra\n\nLater versions work fine without the kext.\n\n\n## Documentation\n\nSee the [xnumon wiki](https://github.com/droe/xnumon/wiki) for further\ndocumentation.  While the wiki is still work in progress, some useful starting\npoints:\n\n-   `cat /var/log/xnumon.log | jq 'select(.eventcode==0)'`\n-   `xnumonctl`\n-   `xnumon -h`\n-   `dmesg | grep xnumon`\n\n\n## Installing\n\nThe installer package published on the\n[xnumon website](https://www.roe.ch/xnumon)\nwill install the daemon, the control utility and a default configuration which\nby default will log to `/var/log/xnumon.log` in JSON Lines format.  It will\nalso install a matching newsyslog configuration and the kernel extension.\n\nAs of macOS 10.13 High Sierra, the kext needs to be explicitly approved by the\nuser before it can be loaded.  For enterprise deployments, you will want to\nallow the Team ID C9BFEG985N to bypass user approval using `spctl kext-consent`\nfrom Recovery OS or NetBoot/NetInstall/NetRestore images, or using Mobile\nDevice Management (MDM).  For details, refer to\n[TN2459](https://developer.apple.com/library/archive/technotes/tn2459/).\n\nThe extensively commented\n[default configuration](pkg/configuration.plist-default.in)\nis installed to\n`/Library/Application Support/ch.roe.xnumon/configuration.plist-default`.\nWhile the defaults are as sensible as possible, you will most likely want to\nmaintain a custom configuration at\n`/Library/Application Support/ch.roe.xnumon/configuration.plist` to be used\nin favour of the default configuration, especially for enterprise deployments.\n\nIn addition to installing xnumon, you will want to make sure that auditd does\nnot clobber the global kernel audit policy.  Make sure the `argv` policy flag\nis enabled in `/etc/security/audit_control`, which is the default.  If you are\nusing `envlevel` `dyld` or `full`, then `arge` is needed in addition to `argv`.\n\nIn order to make the logs useful and to get them out of reach of malware and\nattackers, it is recommended to continuously forward logs to central log\ncollection infrastructure.  A minimal sample Splunk configuration for ingesting\nxnumon logs can be found in `extra/splunk`.\n\n\n## Uninstalling\n\n~~~\nxnumonctl uninstall\n~~~\n\nThis will remove all traces of this package from your system, including logs\nat the default location `/var/log/xnumon.log*`, but not including the config\nat `/Library/Application Support/ch.roe.xnumon/configuration.plist` unless it\nis the same as the default config.\n\n\n## Build Dependencies\n\nBuilding an unsigned userland binary and kernel extension requires Xcode\ncommand line tools.  The userland binary requires only the CoreFoundation and\nSecurity frameworks and libbsm; there are no third-party dependencies.\n\nBuilding a signed userland binary requires an Application Developer ID\ncertificate from Apple.\n\nBuilding a signed kernel extension requires a Kext Developer ID certificate\nfrom Apple.\n\nBuilding signed binary packages requires `pandoc` and an Installer Developer ID\ncertificate from Apple.\n\n\n## Debugging\n\nUse `make test` while xnumon is logging to `/var/log/xnumon.log` to execute a\nset of automated test cases, exercising different APIs and automatically\nchecking the log file for the expected events.  Submitting a pull request with\na failing testcase is the best way to report bugs.\n\nUse the metrics in eventcode 1 events to monitor xnumon internals, possibly\nreducing the interval it gets generated in the configuration.\n\nEnable `debug` in the configuration and run `xnumonctl logstderr` to change\nthe launchd plist for xnumon to send stderr to `/var/log/xnumon.stderr`.\nThis will allow you to get context information for fatal events that would\notherwise only be visible in one of the eventcode 1 metrics.\n\nFor short-term debugging during development you can also just unload xnumon\nusing `xnumonctl unload` and run xnumon with `-o debug=true` on the command\nline.\n\nPass `DEBUG=1` to make in order to build a debug version of xnumon that\nincludes symbols, assertions and additional debugging code.  See make file\nfor details.\n\nTo load an unsigned, modified kext for testing and development, you need to\ndisable System Integrity Protection (SIP) for kexts.  Reboot to Recovery OS by\npressing \u003ckbd\u003ecmd⌘\u003c/kbd\u003e+\u003ckbd\u003er\u003c/kbd\u003e during boot and from within the repair\nconsole, run `csrutil enable --without kext`.  This will also turn off the kext\nuser consent requirement of High Sierra and later.\n\n\n## Copyright and License\n\nCopyright (c) 2017-2019, [Daniel Roethlisberger](//daniel.roe.ch/).  \nAll rights reserved.  \nLicensed under the Open Software License version 3.0.  \nContains components licensed under BSD and MIT licenses as well as components\nreleased under the Unlicense.\n\nSee `LICENSE`, `LICENSE.contrib` and `LICENSE.third` as well as the respective\nsource file headers for details.\n\n","funding_links":[],"categories":["Useful tools and guides"],"sub_categories":["[xnumon](https://www.roe.ch/xnumon)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdroe%2Fxnumon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdroe%2Fxnumon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdroe%2Fxnumon/lists"}