json-exec

README

json-exec

A utility for capturing stderr and stdout output from a command and displaying them as JSON messages

---

---

Table of Contents

• 👁️ Overview
• ✅ Requirements
• ✴️ Installation
• ▶️ Execution
  • ➡️ run Command
  • ➡️ version Command
  • ➡️ Sample output messages
• ⛏️ Building from Source
• 📃 License
• ❓ Questions, Issues and Feature Requests

👁️ Overview

json-exec is a simple tool to execute any arbitrary command with a set of arguments and capture its output from stdout and/or stderr and produce a JSON message containing the result.

This utility was created in order to be able to produce consumable logs in JSON format for various services and executables.

Upon execution, json-exec will produce 2 log messages:

• Both messages will contain @level, @timestamp and @message fields as well as any additional fields passed via command-line flags.
• The first log message will contain command and args fields which will be populated with the command and an array of arguments passed to the command, respectively.
• The second log message will contain an exit_code field indicating the command's exit code. Additionally the stdout and stderr fields will contain output from stdout and stderr, respectively, if they are enabled.
• If the command produces and error, an error_message field will also be included in the second message.

✅ Requirements

This software is supported on the following platforms:

• Windows 10 or later (64-bit)
• MacOS (64-bit))
• Linux (64-bit)

There are no additional requirements to use this utility.

✴️ Installation

To install the utility on your system, simply download and unpack the appropriate archive file for your OS and then copy the json-exec binary to a folder on your path.

▶️ Execution

The general usage of json-exec is as follows:

Usage:
  json-exec [command]

Available Commands:
  help        Help about any command
  run         Executes an arbitrary system command with optional flags
  version     Display application version information

Flags:
  -c, --config-file string       Path to the configuration settings file
  -f, --field stringToString     one or more additional fields to include in the output (default [])
  -h, --help                     help for json-exec
      --level-field string       alternate name for the level field (default "@level")
  -l, --log-level string         adjust output log level - must be one of: debug, info, warn, error, fatal, panic or none (default "info")
      --message-field string     alternate name for the message field (default "@message")
      --timestamp-field string   alternate name for the timestamp field (default "@timestamp")

Use "json-exec [command] --help" for more information about a command.

➡️ run Command

The run command allows you to run an arbitrary command with or without arguments.

Usage:
  json-exec run [flags] <command> [command args]

Flags:
  -h, --help            help for run
      --ignore-stderr   ignore stderr output from the command
      --ignore-stdout   ignore stdout output from the command

Global Flags:
  -c, --config-file string       Path to the configuration settings file
  -f, --field stringToString     one or more additional fields to include in the output (default [])
      --level-field string       alternate name for the level field (default "@level")
  -l, --log-level string         adjust output log level - must be one of: debug, info, warn, error, fatal, panic or none (default "info")
      --message-field string     alternate name for the message field (default "@message")
      --timestamp-field string   alternate name for the timestamp field (default "@timestamp")

To run a simple system command without any arguments just call it as you normally would adding json-exec run to the start:

json-exec run chown root:root /root

If you are calling a system command that requires arguments, supply the -- flag before the actual command so that the CLI does not interpret the command arguments as flags to json-exec:

json-exec run -- chown -hR root:root /root

To add extra fields to the output, use the --field flag repeatedly passing key=value for each pair:

json-exec run --field "@level=info" --field "@module=entrypoint" -- chown -hR root:root /root
json-exec run --field "app=myapp" -- chown -hR root:root /root

To ignore output from stderr, use the --ignore-stderr flag. To ignore output from stdout, use the --ignore-stdout flag.

json-exec run --ignore-stderr cat /etc/hosts
json-exec run --ignore-stdout curl -v https://google.com

➡️ version Command

The version command displays version information.

Usage:
  json-exec version [flags]

Flags:
  -h, --help        help for version
  -p, --plaintext   output plaintext instead of JSON
  -v, --verbose     display full version information including build and release date

Global Flags:
  -c, --config-file string       Path to the configuration settings file
  -f, --field stringToString     one or more additional fields to include in the output (default [])
      --level-field string       alternate name for the level field (default "@level")
  -l, --log-level string         adjust output log level - must be one of: debug, info, warn, error, fatal, panic or none (default "info")
      --message-field string     alternate name for the message field (default "@message")
      --timestamp-field string   alternate name for the timestamp field (default "@timestamp")

To display the version information in JSON output:

json-exec version

In this case only a single message will be printed and will include the build, release_date and version fields.

To display the version information in plaintext:

json-exec version --plaintext

➡️ Sample output messages

Attempting to change ownership on /root as a normal user:

{"@level":"info","@message":"Executing command: chown root:root /root","@timestamp":"2021-04-30T01:47:33.546988Z","args":["root:root","/root"],"command":"chown"}

{"@level":"warn","@message":"Command completed with exit code 1","@timestamp":"2021-04-30T01:47:33.547896Z","error_message":"exit status 1","exitCode":1,"stderr":"chown: changing ownership of '/root': Operation not permitted\n","stdout":""}

Attempting to recursively change ownership on /root as root:

{"@level":"info","@message":"Executing command: chown -hR root:root /root","@timestamp":"2021-04-30T01:49:42.127222Z","args":["-hR","root:root","/root"],"command":"chown"}

{"@level":"info","@message":"Command completed with exit code 0","@timestamp":"2021-04-30T01:49:42.142997Z","exitCode":0,"stderr":"","stdout":""}

cat'ing the /etc/group file (notice the newlines are replaced automatically with \n characters):

{"@level":"info","@message":"Executing command: cat /etc/hosts","@timestamp":"2021-04-30T01:52:45.072169Z","args":["/etc/hosts"],"command":"cat"}

{"@level":"info","@message":"Command completed with exit code 0","@timestamp":"2021-04-30T01:52:45.072848Z","exitCode":0,"stderr":"","stdout":"# This file was automatically generated by WSL. To stop automatic generation of this file, add the following entry to /etc/wsl.conf:\n# [network]\n# generateHosts = false\n127.0.0.1\tlocalhost\n127.0.1.1\tJOSH-DESKTOP.localdomain\tJOSH-DESKTOP\n\n# The following lines are desirable for IPv6 capable hosts\n::1     ip6-localhost ip6-loopback\nfe00::0 ip6-localnet\nff00::0 ip6-mcastprefix\nff02::1 ip6-allnodes\nff02::2 ip6-allrouters\n"}

Executing the version sub-command:

{"@level":"info","@message":"json-exec version 0.1.0 build abcdef (Released 29 Apr 2021)","@timestamp":"2021-04-30T01:42:54.222477Z","build":"abcdef","release_date":"29 Apr 2021","version":"0.1.0"}

Executing the version sub-command with the --plaintext option:

json-exec version 0.1.0 build abcdef (Released 29 Apr 2021)

⛏️ Building from Source

In order to build project from source, you will need the following software installed on your system:

• go 1.16 or later (https://golang.org/dl/)
• Standard build tools (eg: git, make, tar and zip)
• If building on a Windows machine, use WSL2

Once these tools have been installed, change to the root directory of the repository and run the command:

make clean all

Upon completion, the dist folder will contain dev and release subfolders with folders for each of the supported platforms.

📃 License

This utility is distributed under the MIT license.

❓ Questions, Issues and Feature Requests

If you have questions about this project, find a bug or wish to submit a feature request, please submit an issue.