From f0b9662c5e3921cfb8daf112962c69eb9b792e7a Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Wed, 20 Jul 2022 07:54:50 -0700 Subject: [PATCH 1/7] add docs --- jc/parsers/x509_cert.py | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/jc/parsers/x509_cert.py b/jc/parsers/x509_cert.py index 399f332a..ef7187d9 100644 --- a/jc/parsers/x509_cert.py +++ b/jc/parsers/x509_cert.py @@ -6,6 +6,11 @@ You can convert other certificate formats (e.g. PKCS #7, PKCS #12, etc.) by processing them through a program like `openssl` and sending the output to `jc`. (See examples below) +> Note: `jc` does not verify the integrity of the certificate, which +> requires calculating the hash of the certificate body and comparing it to +> the the hash in the certificate's signature after it is decrypted with the +> issuer certificate's public key. + Usage (cli): $ cat certificate.pem | jc --x509-cert @@ -119,6 +124,39 @@ Schema: } } + Subject Alternative Name: + { + "extn_id": "subject_alt_name", + "critical": boolean, + "extn_value": [ + string + ] + } + + Certificate Policies: + { + "extn_id": "certificate_policies", + "critical": boolean, + "extn_value": [ + { + "policy_identifier": string, + "policy_qualifiers": [ array or null + { + "policy_qualifier_id": string, + "qualifier": string + } + ] + } + ] + } + + Signed Certificate Timestamp List + { + "extn_id": "signed_certificate_timestamp_list", + "critical": boolean, + "extn_value": string # [0] + } + Examples: $ cat entrust-ec1.pem | jc --x509-cert -p From b2271713e117bae468bb535121b2a5067cab913e Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Wed, 20 Jul 2022 07:56:39 -0700 Subject: [PATCH 2/7] add to docs --- docs/parsers/x509_cert.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/parsers/x509_cert.md b/docs/parsers/x509_cert.md index 08512ab5..ad4ee7b5 100644 --- a/docs/parsers/x509_cert.md +++ b/docs/parsers/x509_cert.md @@ -11,6 +11,11 @@ You can convert other certificate formats (e.g. PKCS #7, PKCS #12, etc.) by processing them through a program like `openssl` and sending the output to `jc`. (See examples below) +> Note: `jc` does not verify the integrity of the certificate, which +> requires calculating the hash of the certificate body and comparing it to +> the the hash in the certificate's signature after it is decrypted with the +> issuer certificate's public key. + Usage (cli): $ cat certificate.pem | jc --x509-cert @@ -124,6 +129,39 @@ Schema: } } + Subject Alternative Name: + { + "extn_id": "subject_alt_name", + "critical": boolean, + "extn_value": [ + string + ] + } + + Certificate Policies: + { + "extn_id": "certificate_policies", + "critical": boolean, + "extn_value": [ + { + "policy_identifier": string, + "policy_qualifiers": [ array or null + { + "policy_qualifier_id": string, + "qualifier": string + } + ] + } + ] + } + + Signed Certificate Timestamp List + { + "extn_id": "signed_certificate_timestamp_list", + "critical": boolean, + "extn_value": string # [0] + } + Examples: $ cat entrust-ec1.pem | jc --x509-cert -p From abf6ea1fec0992e8628498525331e16f0587ac4b Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Sun, 21 Aug 2022 16:20:13 -0700 Subject: [PATCH 3/7] doc update --- docs/lib.md | 17 ++++++++++++++--- jc/lib.py | 17 ++++++++++++++--- 2 files changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/lib.md b/docs/lib.md index 73c50f46..25c571bc 100644 --- a/docs/lib.md +++ b/docs/lib.md @@ -34,11 +34,22 @@ Parse the string data using the supplied parser module. This function provides a high-level API to simplify parser use. This function will call built-in parsers and custom plugin parsers. -Example: +Example (standard parsers): >>> import jc - >>> jc.parse('date', 'Tue Jan 18 10:23:07 PST 2022') - {'year': 2022, 'month': 'Jan', 'month_num': 1, 'day'...} + >>> date_obj = jc.parse('date', 'Tue Jan 18 10:23:07 PST 2022') + >>> print(f'The year is: {date_obj["year"]}') + The year is: 2022 + +Example (streaming parsers): + + >>> import jc + >>> ping_gen = jc.parse('ping_s', ping_output.splitlines()) + >>> for item in ping_gen: + >>> print(f'Response time: {item["time_ms"]} ms') + Response time: 102 ms + Response time: 109 ms + ... To get a list of available parser module names, use `parser_mod_list()`. diff --git a/jc/lib.py b/jc/lib.py index 2675a43f..9356323d 100644 --- a/jc/lib.py +++ b/jc/lib.py @@ -197,11 +197,22 @@ def parse( This function provides a high-level API to simplify parser use. This function will call built-in parsers and custom plugin parsers. - Example: + Example (standard parsers): >>> import jc - >>> jc.parse('date', 'Tue Jan 18 10:23:07 PST 2022') - {'year': 2022, 'month': 'Jan', 'month_num': 1, 'day'...} + >>> date_obj = jc.parse('date', 'Tue Jan 18 10:23:07 PST 2022') + >>> print(f'The year is: {date_obj["year"]}') + The year is: 2022 + + Example (streaming parsers): + + >>> import jc + >>> ping_gen = jc.parse('ping_s', ping_output.splitlines()) + >>> for item in ping_gen: + >>> print(f'Response time: {item["time_ms"]} ms') + Response time: 102 ms + Response time: 109 ms + ... To get a list of available parser module names, use `parser_mod_list()`. From 51eb2c9fa88e406f00bc1f5221e42bdbefe95f48 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Sun, 21 Aug 2022 16:23:56 -0700 Subject: [PATCH 4/7] doc update --- docs/readme.md | 7 ++++++- jc/__init__.py | 7 ++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/readme.md b/docs/readme.md index c87a0766..2c0d7e6d 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -11,12 +11,17 @@ and file-types to dictionaries and lists of dictionaries. ## Interactive Documentation +Using `jc` in your python programs: + >>> help('jc') >>> help('jc.lib') + >>> jc.get_help('parser_module_name') + +Developing `jc` parsers: + >>> help('jc.utils') >>> help('jc.streaming') >>> help('jc.parsers.universal') - >>> jc.get_help('parser_module_name') ## Online Documentation diff --git a/jc/__init__.py b/jc/__init__.py index bbf8ab97..fd297d59 100644 --- a/jc/__init__.py +++ b/jc/__init__.py @@ -7,12 +7,17 @@ and file-types to dictionaries and lists of dictionaries. ## Interactive Documentation +Using `jc` in your python programs: + >>> help('jc') >>> help('jc.lib') + >>> jc.get_help('parser_module_name') + +Developing `jc` parsers: + >>> help('jc.utils') >>> help('jc.streaming') >>> help('jc.parsers.universal') - >>> jc.get_help('parser_module_name') ## Online Documentation From 9699a184d188dc99f554118fec97eedd99d55041 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Wed, 24 Aug 2022 09:07:34 -0700 Subject: [PATCH 5/7] add exit code with --meta-out to readme --- README.md | 40 ++++++++++++++++++++++++++++++++++++++- templates/readme_template | 40 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 78 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 91352111..ffb06377 100644 --- a/README.md +++ b/README.md @@ -292,7 +292,9 @@ option. ### Exit Codes Any fatal errors within `jc` will generate an exit code of `100`, otherwise the -exit code will be `0`. When using the "magic" syntax (e.g. `jc ifconfig eth0`), +exit code will be `0`. + +When using the "magic" syntax (e.g. `jc ifconfig eth0`), `jc` will store the exit code of the program being parsed and add it to the `jc` exit code. This way it is easier to determine if an error was from the parsed program or `jc`. @@ -306,6 +308,42 @@ Consider the following examples using `ifconfig`: | `0` | `100` | `100` | Error in `jc` | | `1` | `100` | `101` | Error in both `ifconfig` and `jc` | +When using the "magic" syntax you can also retrieve the exit code of the called +program by using the `--meta-out` or `-M` option. This will append a `_jc_meta` +object to the output that will include the magic command information, including +the exit code. + +Here is an example with `ping`: +```json +$ jc --meta-out -p ping -c2 192.168.1.252 +{ + "destination_ip": "192.168.1.252", + "data_bytes": 56, + "pattern": null, + "destination": "192.168.1.252", + "packets_transmitted": 2, + "packets_received": 0, + "packet_loss_percent": 100.0, + "duplicates": 0, + "responses": [ + { + "type": "timeout", + "icmp_seq": 0, + "duplicate": false + } + ], + "_jc_meta": { + "parser": "ping", + "timestamp": 1661357115.27949, + "magic_command": [ + "ping", + "-c2", + "192.168.1.252" + ], + "magic_command_exit": 2 + } +} +``` ### Setting Custom Colors via Environment Variable You can specify custom colors via the `JC_COLORS` environment variable. The diff --git a/templates/readme_template b/templates/readme_template index c4e64d89..a6a5ff81 100644 --- a/templates/readme_template +++ b/templates/readme_template @@ -173,7 +173,9 @@ option. ### Exit Codes Any fatal errors within `jc` will generate an exit code of `100`, otherwise the -exit code will be `0`. When using the "magic" syntax (e.g. `jc ifconfig eth0`), +exit code will be `0`. + +When using the "magic" syntax (e.g. `jc ifconfig eth0`), `jc` will store the exit code of the program being parsed and add it to the `jc` exit code. This way it is easier to determine if an error was from the parsed program or `jc`. @@ -187,6 +189,42 @@ Consider the following examples using `ifconfig`: | `0` | `100` | `100` | Error in `jc` | | `1` | `100` | `101` | Error in both `ifconfig` and `jc` | +When using the "magic" syntax you can also retrieve the exit code of the called +program by using the `--meta-out` or `-M` option. This will append a `_jc_meta` +object to the output that will include the magic command information, including +the exit code. + +Here is an example with `ping`: +```json +$ jc --meta-out -p ping -c2 192.168.1.252 +{ + "destination_ip": "192.168.1.252", + "data_bytes": 56, + "pattern": null, + "destination": "192.168.1.252", + "packets_transmitted": 2, + "packets_received": 0, + "packet_loss_percent": 100.0, + "duplicates": 0, + "responses": [ + { + "type": "timeout", + "icmp_seq": 0, + "duplicate": false + } + ], + "_jc_meta": { + "parser": "ping", + "timestamp": 1661357115.27949, + "magic_command": [ + "ping", + "-c2", + "192.168.1.252" + ], + "magic_command_exit": 2 + } +} +``` ### Setting Custom Colors via Environment Variable You can specify custom colors via the `JC_COLORS` environment variable. The From 6c38a3bbaac87bbaa7155f85c386a9aade99a543 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Wed, 24 Aug 2022 09:11:06 -0700 Subject: [PATCH 6/7] add echo $? to show exit code --- README.md | 4 +++- templates/readme_template | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ffb06377..c6fa2030 100644 --- a/README.md +++ b/README.md @@ -314,7 +314,7 @@ object to the output that will include the magic command information, including the exit code. Here is an example with `ping`: -```json +```bash $ jc --meta-out -p ping -c2 192.168.1.252 { "destination_ip": "192.168.1.252", @@ -343,6 +343,8 @@ $ jc --meta-out -p ping -c2 192.168.1.252 "magic_command_exit": 2 } } +$ echo $? +2 ``` ### Setting Custom Colors via Environment Variable diff --git a/templates/readme_template b/templates/readme_template index a6a5ff81..963c8176 100644 --- a/templates/readme_template +++ b/templates/readme_template @@ -195,7 +195,7 @@ object to the output that will include the magic command information, including the exit code. Here is an example with `ping`: -```json +```bash $ jc --meta-out -p ping -c2 192.168.1.252 { "destination_ip": "192.168.1.252", @@ -224,6 +224,8 @@ $ jc --meta-out -p ping -c2 192.168.1.252 "magic_command_exit": 2 } } +$ echo $? +2 ``` ### Setting Custom Colors via Environment Variable From 4746cb381424864bfdecbed86237c6018ab053fe Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Wed, 24 Aug 2022 09:24:03 -0700 Subject: [PATCH 7/7] add --meta-out info to exit code section --- man/jc.1 | 47 ++++++++++++++++++++++++++++++++++++-- templates/manpage_template | 45 +++++++++++++++++++++++++++++++++++- 2 files changed, 89 insertions(+), 3 deletions(-) diff --git a/man/jc.1 b/man/jc.1 index 2e9f1711..8febd814 100644 --- a/man/jc.1 +++ b/man/jc.1 @@ -1,4 +1,4 @@ -.TH jc 1 2022-08-21 1.21.0 "JSON Convert" +.TH jc 1 2022-08-24 1.21.0 "JSON Convert" .SH NAME \fBjc\fP \- JSON Convert JSONifies the output of many CLI tools and file-types .SH SYNOPSIS @@ -682,7 +682,9 @@ Generate Bash shell completion script Generate Zsh shell completion script .SH EXIT CODES -Any fatal errors within \fBjc\fP will generate an exit code of \fB100\fP, otherwise the exit code will be \fB0\fP. When using the "Magic" syntax (e.g. \fBjc ifconfig eth0\fP), \fBjc\fP will store the exit code of the program being parsed and add it to the \fBjc\fP exit code. This way it is easier to determine if an error was from the parsed program or \fBjc\fP. +Any fatal errors within \fBjc\fP will generate an exit code of \fB100\fP, otherwise the exit code will be \fB0\fP. + +When using the "magic" syntax (e.g. \fBjc ifconfig eth0\fP), \fBjc\fP will store the exit code of the program being parsed and add it to the \fBjc\fP exit code. This way it is easier to determine if an error was from the parsed program or \fBjc\fP. Consider the following examples using \fBifconfig\fP: @@ -696,6 +698,47 @@ ifconfig exit code = \fB0\fP, jc exit code = \fB100\fP, combined exit code = \fB ifconfig exit code = \fB1\fP, jc exit code = \fB100\fP, combined exit code = \fB101\fP (error in both ifconfig and jc) .RE +When using the "magic" syntax you can also retrieve the exit code of the called +program by using the \fB--meta-out\fP or \fB-M\fP option. This will append a \fB_jc_meta\fP +object to the output that will include the magic command information, including +the exit code. + +Here is an example with \fBping\fP: +.RS +.nf +$ jc --meta-out -p ping -c2 192.168.1.252 +{ + "destination_ip": "192.168.1.252", + "data_bytes": 56, + "pattern": null, + "destination": "192.168.1.252", + "packets_transmitted": 2, + "packets_received": 0, + "packet_loss_percent": 100.0, + "duplicates": 0, + "responses": [ + { + "type": "timeout", + "icmp_seq": 0, + "duplicate": false + } + ], + "_jc_meta": { + "parser": "ping", + "timestamp": 1661357115.27949, + "magic_command": [ + "ping", + "-c2", + "192.168.1.252" + ], + "magic_command_exit": 2 + } +} +$ echo $? +2 +.fi +.RE + .SH ENVIRONMENT \fBCustom Colors\fP diff --git a/templates/manpage_template b/templates/manpage_template index 7c6c7d33..c1bfacf6 100644 --- a/templates/manpage_template +++ b/templates/manpage_template @@ -87,7 +87,9 @@ Generate Bash shell completion script Generate Zsh shell completion script .SH EXIT CODES -Any fatal errors within \fBjc\fP will generate an exit code of \fB100\fP, otherwise the exit code will be \fB0\fP. When using the "Magic" syntax (e.g. \fBjc ifconfig eth0\fP), \fBjc\fP will store the exit code of the program being parsed and add it to the \fBjc\fP exit code. This way it is easier to determine if an error was from the parsed program or \fBjc\fP. +Any fatal errors within \fBjc\fP will generate an exit code of \fB100\fP, otherwise the exit code will be \fB0\fP. + +When using the "magic" syntax (e.g. \fBjc ifconfig eth0\fP), \fBjc\fP will store the exit code of the program being parsed and add it to the \fBjc\fP exit code. This way it is easier to determine if an error was from the parsed program or \fBjc\fP. Consider the following examples using \fBifconfig\fP: @@ -101,6 +103,47 @@ ifconfig exit code = \fB0\fP, jc exit code = \fB100\fP, combined exit code = \fB ifconfig exit code = \fB1\fP, jc exit code = \fB100\fP, combined exit code = \fB101\fP (error in both ifconfig and jc) .RE +When using the "magic" syntax you can also retrieve the exit code of the called +program by using the \fB--meta-out\fP or \fB-M\fP option. This will append a \fB_jc_meta\fP +object to the output that will include the magic command information, including +the exit code. + +Here is an example with \fBping\fP: +.RS +.nf +$ jc --meta-out -p ping -c2 192.168.1.252 +{ + "destination_ip": "192.168.1.252", + "data_bytes": 56, + "pattern": null, + "destination": "192.168.1.252", + "packets_transmitted": 2, + "packets_received": 0, + "packet_loss_percent": 100.0, + "duplicates": 0, + "responses": [ + { + "type": "timeout", + "icmp_seq": 0, + "duplicate": false + } + ], + "_jc_meta": { + "parser": "ping", + "timestamp": 1661357115.27949, + "magic_command": [ + "ping", + "-c2", + "192.168.1.252" + ], + "magic_command_exit": 2 + } +} +$ echo $? +2 +.fi +.RE + .SH ENVIRONMENT \fBCustom Colors\fP