x-ray-client
x-ray-client is a command-line tool that connects to Process X-Ray and Network X-Ray’s system extensions. x-ray-client receives the same data as the GUI portions of Process & Network X-Ray. x-ray-client can save this data into rotating log files or print it to standard out.
By printing the log records to standard out, you can feed the log records into 3rd-party tools to support new functionality.
The screenshots below show these key functionalities.
--help
Supplying the “-h” or “--help” option prints a summary of the x-ray-client’s usage.
The orange vertical bars show the argument groups that are discussed below.
logging
x-ray-client can save the event records to rotating log files. Each type of event gets its own log file.
The “--log <directory>” argument tells x-ray-client to create rotating log files and where the finished log files should go.
The “--workinglog <directory>” argument tells x-ray-client to where to write the currently open log files (the working log files). Once a working log file is closed, the file will be moved to the final log location specified with the “--log” argument. If you do not provide the “--workinglog” argument, the working log files are saved to the /tmp directory.
By keeping the finished log file and working log file directories separate, you can guarantee that any file showing up in the finished log directory is done and is ready to be processed. For example, you may have an agent that watches for new files added to the finished log file directory, and as soon as a new file is added, the agent uploads the file to a secure log facility.
The “--min” argument tells x-ray-client to rotate the log files every 10 minutes. Without this argument, x-ray-client rotates the log files every hour.
When the log files are rotated every hour, the file format is
<event-type>_YYYY-MM-DDThh.log
When log files are rotated every 10 minutes, the file format is
<event-type>_YYYY-MM-DDThh-mm.log
The timestamp uses UTC time.
The event-types for Process X-Ray are:
exec - process executes a new program
exit - process exits
fork - process is created from a parent process
Printing to standard out
The “-e”, “-x”, and “-k” arguments direct x-ray-client to print to standard out the “execution”, “exit”, and “fork” events respectively.
The screenshot above shows the output when the “-e” argument is provided. Each record is printed as a JSON line.
The orange box shows a single JSON line record. In the screenshot there are 3 whole records shown and part of a 4th record.
Piping records to 3rd-party programs
The ability to print to standard out was developed to allow individuals and organizations to pipe the records in real-time to other programs.
For example, you might use a custom logging program that sends the records immediately across the network to a logging server. Or you may want to build a real-time intrusion detection system that detects events immediately and sends out a notification.
The example in the screenshot above simply pipes the execution events to a one-line awk program that prints part of each JSON record. This part of the exec program shows the program followed by any arguments (essentially the argv array passed to a program).
In the screenshot, 7 execution events are shown. These 7 events can be be grouped into 3 groups.
ps command - the first group is the single “/bin/ps” command. This is actually launched by Process X-Ray’s endpoint system extension to capture the currently running programs.
3 shell commands - the second group are three commands launched from a Terminal window: “ls”, “view secret_document.txt”, and “rm secret_document.txt”.
3 screenshot executions - the last three programs executions (screen capture, xpcproxy, and screencaptureui.app) are programs the macOS started when entered the keyboard shortcut to capture this screenshot (cmd-shift-4).