initial commit

.github/workflows/build.yml

@@ -0,0 +1,37 @@
+name: Build
+
+on:
+  push:
+    branches: 
+      - main
+  pull_request:
+    paths:
+      - 'examples/*'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v2
+
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.17
+
+      - name: Cache Go modules
+        uses: actions/cache@v2
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+      # Here, we simply print the exact go version, to have it as part of the
+      # action's output, which might be convenient.
+      - name: Print Go version
+        run: go version
+
+      - name: Build examples
+        run: for dir in examples/*/; do go build -o $dir/bin $dir/main.go; done

.github/workflows/test.yml

@@ -0,0 +1,62 @@
+name: Test
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - '**.go'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v2
+
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.17
+
+      - name: Cache Go modules
+        uses: actions/cache@v2
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+            
+      - name: Print Go version
+        run: go version
+
+      - name: Verify Go modules
+        run: go mod tidy && git status && git --no-pager diff && git diff-index --quiet HEAD --
+
+      - name: Verify source code formatting
+        run: go fmt ./... && git status && git --no-pager diff && git diff-index --quiet HEAD --
+
+      - name: Install Zmap
+        run: sudo apt install -y zmap
+
+      - name: Print Zmap Version
+        run: zmap --version
+
+      - name: Test
+        run: |
+          export ZMAP_BINARY=$(which zmap)
+          echo "Found zmap binary: "$ZMAP_BINARY
+          sudo setcap cap_net_raw,cap_net_admin=eip $ZMAP_BINARY
+          sudo getcap $ZMAP_BINARY
+          go test -coverprofile=c.out ./...
+        
+      - name: Install goveralls
+        run: go install github.com/mattn/goveralls@latest
+
+      - name: Create coverage report
+        run: go tool cover -func=c.out
+
+      - name: Send coverage report
+        env:
+            COVERALLS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: goveralls -coverprofile=c.out -service=github

.gitignore

@@ -0,0 +1,86 @@
+
+# Created by https://www.toptal.com/developers/gitignore/api/visualstudiocode,go,git,macos
+# Edit at https://www.toptal.com/developers/gitignore?templates=visualstudiocode,go,git,macos
+
+### Git ###
+# Created by git for backups. To disable backups in Git:
+# $ git config --global mergetool.keepBackup false
+*.orig
+
+# Created by git when using merge tools for conflicts
+*.BACKUP.*
+*.BASE.*
+*.LOCAL.*
+*.REMOTE.*
+*_BACKUP_*.txt
+*_BASE_*.txt
+*_LOCAL_*.txt
+*_REMOTE_*.txt
+
+### Go ###
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+### Go Patch ###
+/vendor/
+/Godeps/
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+# End of https://www.toptal.com/developers/gitignore/api/visualstudiocode,go,git,macos

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 projecthunt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,133 @@
+<p align="center">
+    <img width="400" src="images/logo.png">
+<p>
+
+<p align="center">
+	<a href="LICENSE">
+		<img src="https://img.shields.io/badge/License-MIT-yellow.svg">
+	</a>
+	<a href="https://pkg.go.dev/github.com/justmumu/zmapgo">
+		<img src="https://pkg.go.dev/badge/github.com/justmumu/zmapgo.svg" alt="Go Reference">
+	</a>
+	<a href="https://goreportcard.com/report/github.com/justmumu/zmapgo">
+        <img src="https://goreportcard.com/badge/github.com/justmumu/zmapgo">
+    </a>
+	<a href="https://github.com/justmumu/zmapgo/actions/workflows/test.yml">
+		<img src="https://github.com/justmumu/zmapgo/actions/workflows/test.yml/badge.svg">
+	</a>
+	<a href="https://github.com/justmumu/zmapgo/actions/workflows/build.yml">
+		<img src="https://github.com/justmumu/zmapgo/actions/workflows/build.yml/badge.svg">
+	</a>
+	<a href='https://coveralls.io/github/justmumu/zmapgo?branch=main'>
+		<img src='https://coveralls.io/repos/github/justmumu/zmapgo/badge.svg?branch=main' alt='Coverage Status' />
+	</a>
+<p>
+
+This library aims to provide to golang developers an idiomatic interface for zmap version 2.1.1.
+
+Inspired by the [nmap](https://github.com/Ullaakut/nmap) library.
+
+## What is Zmap
+[Zmap](https://github.com/zmap/zmap) is a network tool for scanning the entire Internet (or large samples). ZMap is capable of scanning the entire Internet in around 45 minutes on a gigabit network connection, reaching ~98% theoretical line speed.
+
+[More Details](https://github.com/zmap/zmap/wiki)
+
+## Supported Features
+- [x] All of `zmap 2.1.1` native options.
+- [x] Cancellable contexts support
+- [x] Validation for options
+- [x] Async Scanner
+- [x] Blocking Scanner
+
+## TODO
+- [ ] More examples
+
+## Installation
+```bash
+go get github.com/justmumu/zmapgo
+```
+
+## Simple Example
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/justmumu/zmapgo"
+)
+
+func main() {
+    // Create Context
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+
+    // Create Blocking Scanner with InitOptions
+    scanner, err := zmapgo.NewBlockingScanner(
+		zmapgo.WithContext(ctx),
+	)
+	if err != nil {
+		log.Fatalf("unable to create zmap scanner: %v", err)
+	}
+
+    // Add Options to scanner
+    // Equivalent to `zmap ---target-port 80 1.1.1.0/30 --rate 10000 --output-fields saddr,sport --log-file ./log-file.txt --output-file ./output-file.txt`
+    err = scanner.AddOptions(
+		zmapgo.WithTargets("1.1.1.0/30"),
+		zmapgo.WithTargetPort("80"),
+		zmapgo.WithRate("10000"),
+        zmapgo.WithOutputFields([]string{"saddr", "sport"}),
+		zmapgo.WithLogFile("./log-file.txt"),
+		zmapgo.WithOutputFile("./output-file.txt"),
+	)
+	if err != nil {
+		log.Fatalf("unable to add options: %v", err)
+	}
+
+    // Run the scan
+    results, _, _, _, _, fatals, err := scanner.RunBlocking()
+	if err != nil {
+		log.Fatalf("unable to run zmap scan: %v", err)
+	}
+
+    // It's always good to check for fatals.
+	if len(fatals) > 0 {
+		// So zmap did not work as expected and waiting for results would be pointless.
+		for _, fatal := range fatals {
+			log.Printf("[FATAL]: %s", fatal.Message)
+		}
+		os.Exit(1)
+	}
+
+    // Print All Results
+	for _, result := range results {
+		fmt.Printf("%s\n", strings.Repeat("-", 20))
+		for key, value := range result {
+			fmt.Printf("%s: %s\n", key, value)
+		}
+	}
+```
+
+The program output:
+
+```bash
+--------------------
+saddr: 1.1.1.3
+sport: 80
+--------------------
+saddr: 1.1.1.1
+sport: 80
+--------------------
+saddr: 1.1.1.0
+sport: 80
+--------------------
+saddr: 1.1.1.2
+sport: 80
+```
+## LICENCE
+This project is under [MIT License](LICENSE)

constants.go

@@ -0,0 +1,20 @@
+package zmapgo
+
+type BandwidthUnit string
+
+var (
+	UnitBandwidthBps  BandwidthUnit = "B"
+	UnitBandwidthKbps BandwidthUnit = "K"
+	UnitBandwidthMbps BandwidthUnit = "M"
+	UnitBandwidthGbps BandwidthUnit = "G"
+)
+
+type VerbosityLevel string
+
+var (
+	VerbosityLevel1 VerbosityLevel = "1"
+	VerbosityLevel2 VerbosityLevel = "2"
+	VerbosityLevel3 VerbosityLevel = "3"
+	VerbosityLevel4 VerbosityLevel = "4"
+	VerbosityLevel5 VerbosityLevel = "5"
+)

errors.go

@@ -0,0 +1,13 @@
+package zmapgo
+
+import "errors"
+
+var (
+	// ErrNmapNotInstalled means that upon trying to manually locate zmap in the user's path,
+	// it was not found. Either use the WithBinaryPath method to set it manually, or make sure that
+	// the nmap binary is present in the user's $PATH.
+	ErrZmapNotInstalled = errors.New("zmap binary was not found")
+
+	// ErrScanTimeout means that the provided context was done before the scanner finished its scan.
+	ErrScanTimeout = errors.New("zmap scan timed out")
+)