From add48ca5de18c90cee46d8db925f240f9aca25f6 Mon Sep 17 00:00:00 2001 From: Sascha Steinbiss Date: Sun, 25 Aug 2019 10:31:35 +0200 Subject: [PATCH] Update README.md --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/README.md b/README.md index b1d24d8..bf4189e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,76 @@ gommunityid is a Golang implementation of the [Community ID flow hashing algorithm](https://github.com/corelight/community-id-spec). Its API design was clearly and obviously inspired by the [Python reference implementation](https://github.com/corelight/pycommunityid). +## Usage + +```Go +package main + +import ( + "fmt" + "net" + + "github.com/satta/gommunityid" +) + +func main() { + // Get instance for version 1, seed 0 + cid, _ := gommunityid.GetCommunityIDByVersion(1, 0) + + // Obtain flow tuple. This can be done any way you like. + ft := gommunityid.MakeFlowTuple(net.IPv4(1, 2, 3, 4), net.IPv4(5, 6, 7, 8), 9, 10, 1) + + // Calculate Base64-encoded value + communityid := cid.CalcBase64(ft) + fmt.Printf("%s\n", communityid) + + // Calculate hex-encoded value + communityid = cid.CalcHex(ft) + fmt.Printf("%s\n", communityid) + + // Calculate byte slice + communityidByte := cid.Calc(ft) + fmt.Printf("%v\n", communityidByte) +} +``` +There is also a [convenience function](https://godoc.org/github.com/satta/gommunityid#PcapFlowTupleSource) for parsing pcap files and automated FlowTuple generation for all supported protocols. + +## Command line interface + +This package builds a simple [command line tool](cmd/gommunityid.go) to calculate IDs for pcaps: +``` +$ ./gommunityid pcap +Usage: gommunityid pcap [options] + -seed uint + seed value (default 0) + -version uint + Community ID version (default 1) +$ gommunityid pcap testdata/tcp.pcap +1071580904.891921 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80 +1071580905.035577 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855 +1071580905.035724 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80 +1071580905.037333 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80 +1071580905.181581 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855 +1071580905.184528 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855 +1071580905.184844 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80 +1071580905.184698 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855 +1071580905.184920 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80 +1071580905.184736 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855 +1071580905.203025 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80 +1071580905.346457 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855 +``` +and explicit tuples: +``` +$ gommunityid tuple +Usage: gommunityid tuple [options] + -seed uint + seed value (default 0) + -version uint + Community ID version (default 1) +$ gommunityid tuple 6 66.35.250.204 128.232.110.120 80 34855 +1:LQU9qZlK+B5F3KDmev6m5PMibrg= +``` + ## Author/Contact Sascha Steinbiss