Merge pull request #4 from picatz/update

Update

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Go
+      uses: actions/setup-go@v2
+      with:
+        go-version: 1.17
+
+    - name: Setup Cache
+      uses: actions/cache@v2
+      with:
+        # In order:
+        # * Module download cache
+        # * Build cache (Linux)
+        # * Build cache (Mac)
+        # * Build cache (Windows)
+        path: |
+          ~/go/pkg/mod
+          ~/.cache/go-build
+          ~/Library/Caches/go-build
+          %LocalAppData%\go-build
+        key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+        restore-keys: |
+          ${{ runner.os }}-go-
+
+    - name: Install LibPcap
+      run: sudo apt-get install -y libpcap-dev
+
+    - name: Build
+      run: go build -v ./...
+
+    - name: Test
+      run: go test -v ./...

README.md

@@ -1,11 +1,14 @@
 # pj
 
-Command-line application to convert packets into json.
+Command-line application to convert network packets into JSON.
 
 ## Installation
 
 ```console
-$ go get github.com/picatz/pj
+$ apt-get install -y libpcap-dev
+...
+$ go install github.com/picatz/pj@latest
+...
 ```
 
 ## Help Menu
@@ -26,15 +29,70 @@ $ pj -help
 
 ## Usage
 
+Start capturing packets on the default interface.
+
+```console
+$ pj
+```
+
+Start capturing packets on the `en0` interface.
+
+```console
+$ pj -interface en0
+...
+{"eth":{"dst":"ff:ff:ff:ff:ff:ff","src":"00:0b:82:01:fc:42","type":2048},"ipv4":{"checksum":6026,"dst_ip":"255.255.255.255","flags":"","frag_offset":0,"id":43063,"ihl":5,"length":300,"options":[],"padding":null,"protocol":17,"src_ip":"0.0.0.0","tos":0,"ttl":250,"version":4},"metadata":{"device_addresses":"","device_description":"","device_name":"en0","length":314,"packet_number":3,"time":"1969-12-31T19:00:00-05:00","truncated":false},"udp":{"checksum":40893,"dst_port":67,"src_port":68}}
+...
+```
+
+Save packets captured from the default interface to the `test.pcapng` file. 
+
 ```console
 $ pj -file test.pcapng
 {"eth":{"dst":"ff:ff:ff:ff:ff:ff","src":"00:0b:82:01:fc:42","type":2048},"ipv4":{"checksum":6027,"dst_ip":"255.255.255.255","flags":"","frag_offset":0,"id":43062,"ihl":5,"length":300,"options":[],"padding":null,"protocol":17,"src_ip":"0.0.0.0","tos":0,"ttl":250,"version":4},"metadata":{"device_addresses":"","device_description":"","device_name":"","length":314,"packet_number":1,"time":"1969-12-31T19:00:00-05:00","truncated":false},"udp":{"checksum":22815,"dst_port":67,"src_port":68}}
 ...
 ```
 
+Capture packets on the default interface, filtered using `jq` to select packets that have a TCP layer.
+
 ```console
-$ pj -interface en0
+$ pj | jq 'select(.tcp == null)'
 ...
-{"eth":{"dst":"ff:ff:ff:ff:ff:ff","src":"00:0b:82:01:fc:42","type":2048},"ipv4":{"checksum":6026,"dst_ip":"255.255.255.255","flags":"","frag_offset":0,"id":43063,"ihl":5,"length":300,"options":[],"padding":null,"protocol":17,"src_ip":"0.0.0.0","tos":0,"ttl":250,"version":4},"metadata":{"device_addresses":"","device_description":"","device_name":"en0","length":314,"packet_number":3,"time":"1969-12-31T19:00:00-05:00","truncated":false},"udp":{"checksum":40893,"dst_port":67,"src_port":68}}
+```
+
+
+Capture packets on the default interface, filtered using `jq` to select packets that do NOT have a TCP layer (like DNS using UDP).
+
+```console
+$ pj | jq 'select(.tcp != null)'
 ...
+```
+
+Capture packets on the default interface, filtered using `jq` to select TCP packets with a destination port of 443 (HTTPS).
+
+```console
+$ pj | jq 'select(.tcp.dst_port == 443)'
+```
+
+Capture packets on the default interface, filtered using `jq` to select TCP packets with a destination port or source port of 22 (SSH).
+
+```console
+$ pj | jq 'select(.tcp.dst_port == 22 or .tcp.src_port == 22)'
+```
+
+Capture packets on the default interface, filtered using `jq` to select TCP RST packets.
+
+```console
+$ pj | jq 'select(.tcp.rst)'
+```
+
+Capture packets on the default interface, filtered using `jq` to select TCP FIN packets.
+
+```console
+$ pj | jq 'select(.tcp.fin)'
+```
+
+Capture packets on the default interface, filtered using `jq` to select TCP packet that contain an HTTP response.
+
+```console
+$ pj | jq 'select(.tcp.payload | startswith("HTTP/1.1"))'
 ```

go.sum

@@ -1,20 +1,14 @@
-github.com/google/gopacket v1.1.17 h1:rMrlX2ZY2UbvT+sdz3+6J+pp2z+msCq9MxTU6ymxbBY=
-github.com/google/gopacket v1.1.17/go.mod h1:UdDNZ1OO62aGYVnPhxT1U6aI7ukYtA/kB8vaU0diBUM=
-github.com/google/gopacket v1.1.18 h1:lum7VRA9kdlvBi7/v2p7/zcbkduHaCH/SVVyurs7OpY=
-github.com/google/gopacket v1.1.18/go.mod h1:UdDNZ1OO62aGYVnPhxT1U6aI7ukYtA/kB8vaU0diBUM=
 github.com/google/gopacket v1.1.19 h1:ves8RnFZPGiFnTS0uPQStjwru6uO6h+nlr9j6fL7kF8=
 github.com/google/gopacket v1.1.19/go.mod h1:iJ8V8n6KS+z2U1A8pUwu8bW5SyEMkXJB8Yo/Vo+TKTo=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/lint v0.0.0-20200302205851-738671d3881b/go.mod h1:3xt1FjdF8hUf6vQPIChWIBhFzV8gjjsPE/fR3IyQdNY=
 golang.org/x/mod v0.1.1-0.20191105210325-c90efee705ee/go.mod h1:QqPTAvyqsEbceGzBzNggFXnrqF1CaUcvgkdR5Ot7KZg=
-golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3 h1:0GoQqolDA55aaLxZyTzK/Y2ePZzZTUrRacwib7cNsYQ=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859 h1:R/3boaszxrf1GEUWTVDzSKVwLmSJpwZ1yqXm8j0v2QI=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20190405154228-4b34438f7a67 h1:1Fzlr8kkDLQwqMP8GxrhptBLqZG/EDpiATneiZHY998=
-golang.org/x/sys v0.0.0-20190405154228-4b34438f7a67/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d h1:+R4KGOnez64A81RvjARKc4UT5/tI9ujCIVX+P5KiHuI=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=