Merge pull request #127 from kellyjonbrazil/dev

Dev v1.15.3

CHANGELOG

@@ -1,5 +1,11 @@
 jc changelog
 
+20210426 v1.15.3
+- Add ufw status command parser tested on linux
+- Add ufw-appinfo command parser tested on linux
+- Fix deb package name to conform to standard
+- Add Caveats section to readme and manpage
+
 20210418 v1.15.2
 - Add systeminfo parser tested on Windows
 - Update dig parser to fix an issue with IPv6 addresses in the server field

CONTRIBUTING.md

@@ -17,7 +17,7 @@ Pull requests are the best way to propose changes to the codebase (we use [Githu
 2. Fork the repo and create your branch from `dev`, if available, otherwise `master`.
 3. If you've added code that should be tested, add tests. All new parsers should have several sample outputs and tests.
 4. Documentation is auto-generated from docstrings, so ensure they are clear and accurate.
-5. Ensure the test suite passes.
+5. Ensure the test suite passes. (Note: "**America/Los_Angeles**" timezone should be configured on the test system)
 6. Make sure your code lints.
 7. Issue that pull request!
 
@@ -61,6 +61,11 @@ Good:
 ]
 ```
 
+## Tests
+It is essential to have good command output sample coverage and tests to keep the `jc` parser quality high.
+
+Many parsers include calculated timestamp fields using the `jc.utils.timestamp` class. Naive timestamps created with this class should be generated on a system configured with the "**America/Los_Angeles**" timezone on linux/macOS/unix and "**Pacific Standard Time**" timezone on Windows for tests to pass on the Github Actions CI tests. This timezone should be configured on your local system before running the tests locally, as well.
+
 ## Any contributions you make will be under the MIT Software License
 In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
 

EXAMPLES.md

@@ -3126,6 +3126,115 @@ traceroute -m 3 8.8.8.8 | jc --traceroute -p          # or:  jc -p traceroute -m
   ]
 }
 ```
+### ufw status
+```bash
+ufw status verbose  | jc --ufw -p          # or jc -p ufw status verbose
+```
+```json
+{
+  "status": "active",
+  "logging": "on",
+  "logging_level": "low",
+  "default": "deny (incoming), allow (outgoing), disabled (routed)",
+  "new_profiles": "skip",
+  "rules": [
+    {
+      "action": "ALLOW",
+      "action_direction": "IN",
+      "index": null,
+      "network_protocol": "ipv4",
+      "to_interface": "any",
+      "to_transport": "any",
+      "to_service": null,
+      "to_ports": [
+        22
+      ],
+      "to_ip": "0.0.0.0",
+      "to_ip_prefix": 0,
+      "comment": null,
+      "from_ip": "0.0.0.0",
+      "from_ip_prefix": 0,
+      "from_interface": "any",
+      "from_transport": "any",
+      "from_port_ranges": [
+        {
+          "start": 0,
+          "end": 65535
+        }
+      ],
+      "from_service": null
+    },
+    {
+      "action": "ALLOW",
+      "action_direction": "IN",
+      "index": null,
+      "network_protocol": "ipv4",
+      "to_interface": "any",
+      "to_transport": "tcp",
+      "to_service": null,
+      "to_ports": [
+        80,
+        443
+      ],
+      "to_ip": "0.0.0.0",
+      "to_ip_prefix": 0,
+      "comment": null,
+      "from_ip": "0.0.0.0",
+      "from_ip_prefix": 0,
+      "from_interface": "any",
+      "from_transport": "any",
+      "from_port_ranges": [
+        {
+          "start": 0,
+          "end": 65535
+        }
+      ],
+      "from_service": null
+    }
+  ]
+}
+```
+### ufw app info [application]
+```bash
+ufw app info MSN | jc --ufw-appinfo -p          # or:  jc -p ufw app info MSN
+```
+```json
+[
+  {
+    "profile": "MSN",
+    "title": "MSN Chat",
+    "description": "MSN chat protocol (with file transfer and voice)",
+    "tcp_list": [
+      1863,
+      6901
+    ],
+    "udp_list": [
+      1863,
+      6901
+    ],
+    "tcp_ranges": [
+      {
+        "start": 6891,
+        "end": 6900
+      }
+    ],
+    "normalized_tcp_list": [
+      1863,
+      6901
+    ],
+    "normalized_tcp_ranges": [
+      {
+        "start": 6891,
+        "end": 6900
+      }
+    ],
+    "normalized_udp_list": [
+      1863,
+      6901
+    ]
+  }
+]
+```
 ### uname -a
 ```bash
 uname -a | jc --uname -p          # or:  jc -p uname -a

README.md

@@ -62,10 +62,6 @@ The `jc` parsers can also be used as python modules. In this case the output wil
 ```
 Two representations of the data are possible. The default representation uses a strict schema per parser and converts known numbers to int/float JSON values. Certain known values of `None` are converted to JSON `null`, known boolean values are converted, and, in some cases, additional semantic context fields are added.
 
-> Note: Some parsers have calculated epoch timestamp fields added to the output. Unless a timestamp field name has a `_utc` suffix it is considered naive. (i.e. based on the local timezone of the system the `jc` parser was run on). 
->
-> If a UTC timezone can be detected in the text of the command output, the timestamp will be timezone aware and have a `_utc` suffix on the key name. (e.g. `epoch_utc`) No other timezones are supported for aware timestamps.
-
 To access the raw, pre-processed JSON, use the `-r` cli option or the `raw=True` function parameter in `parse()`.
 
 Schemas for each parser can be found at the documentation link beside each parser below.
@@ -102,7 +98,7 @@ pip3 install jc
 | FreeBSD               | `portsnap fetch update && cd /usr/ports/textproc/py-jc && make install clean` |
 | Ansible filter plugin | `ansible-galaxy collection install community.general`                         |
 
-> For more packages and binaries, see https://kellyjonbrazil.github.io/jc-packaging/.
+> For more packages and binaries, see the [jc packaging](https://kellyjonbrazil.github.io/jc-packaging/) site.
 
 ## Usage
 `jc` accepts piped input from `STDIN` and outputs a JSON representation of the previous command's output to `STDOUT`.
@@ -115,8 +111,6 @@ jc [OPTIONS] COMMAND
 ```
 The JSON output can be compact (default) or pretty formatted with the `-p` option.
 
-> Note: For best results set the `LANG` locale environment variable to `C`. For example, either by setting directly on the command-line: `$ LANG=C date | jc --date`, or by exporting to the environment before running commands: `$ export LANG=C`.
-
 ### Parsers
 
 - `--acpi` enables the `acpi` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/acpi))
@@ -182,6 +176,8 @@ The JSON output can be compact (default) or pretty formatted with the `-p` optio
 - `--timedatectl` enables the `timedatectl status` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/timedatectl))
 - `--tracepath` enables the `tracepath` and `tracepath6` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/tracepath))
 - `--traceroute` enables the `traceroute` and `traceroute6` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/traceroute))
+- `--ufw` enables the `ufw status` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ufw))
+- `--ufw-appinfo` enables the `ufw app info [application]` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ufw_appinfo))
 - `--uname` enables the `uname -a` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/uname))
 - `--upower` enables the `upower` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/upower))
 - `--uptime` enables the `uptime` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/uptime))
@@ -230,6 +226,24 @@ Local plugin filenames must be valid python module names, therefore must consist
 
 > Note: The application data directory follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
 
+### Caveats
+**Locale:**
+
+For best results set the `LANG` locale environment variable to `C`. For example, either by setting directly on the command-line:
+```
+$ LANG=C date | jc --date
+```
+or by exporting to the environment before running commands:
+```
+$ export LANG=C
+```
+
+**Timezones:**
+
+Some parsers have calculated epoch timestamp fields added to the output. Unless a timestamp field name has a `_utc` suffix it is considered naive. (i.e. based on the local timezone of the system the `jc` parser was run on).
+
+If a UTC timezone can be detected in the text of the command output, the timestamp will be timezone aware and have a `_utc`P suffix on the key name. (e.g. `epoch_utc`) No other timezones are supported for aware timestamps.
+
 ## Compatibility
 Some parsers like `ls`, `ps`, `dig`, etc. will work on any platform. Other parsers that are platform-specific will generate a warning message if they are used on an unsupported platform. To see all parser information, including compatibility, run `jc -ap`.
 

docs/parsers/ping.md

@@ -97,7 +97,6 @@ Examples:
       ]
     }
 
-
     $ ping -c 3 -p ff cnn.com | jc --ping -p -r
     {
       "destination_ip": "151.101.129.67",