Skip to content

Commit 83f5532

Browse files
vdjagilevvdjagilev
committed
Simplify readme, put links to wiki
1 parent 4d655fe commit 83f5532

File tree

1 file changed

+6
-206
lines changed

1 file changed

+6
-206
lines changed

‎README.md‎

Lines changed: 6 additions & 206 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,6 @@
88

99
A tool that allows you to convert NMAP XML output to html/csv/json/markdown.
1010

11-
## Table of Contents
12-
13-
- [NMAP-Formatter](#nmap-formatter)
14-
- [Table of Contents](#table-of-contents)
15-
- [Usage](#usage)
16-
- [Flags](#flags)
17-
- [Output Options](#output-options)
18-
- [Installation](#installation)
19-
- [Using Go](#using-go)
20-
- [Docker](#docker)
21-
- [Download Binary](#download-binary)
22-
- [Compile](#compile)
23-
- [Example](#example)
24-
- [Use as a library](#use-as-a-library)
25-
2611
## Usage
2712

2813
```bash
@@ -55,215 +40,30 @@ nmap-formatter json [path-to-nmap.xml]
5540
cat nmap.xml | nmap-formatter json
5641
```
5742

58-
It can be also combined with a `jq` tool
59-
60-
```bash
61-
cat nmap.xml | nmap-formatter json | jq
62-
```
63-
64-
List all the found ports and count them:
65-
66-
```bash
67-
nmap-formatter json [nmap.xml] | jq -r '.Host[]?.Port[]?.PortID' | sort | uniq -c
68-
```
69-
70-
```
71-
1 "22"
72-
2 "80"
73-
1 "8080"
74-
```
75-
76-
another example where only those hosts are selected, which have port where some http service is running:
77-
78-
```bash
79-
nmap-formatter json [nmap.xml] | jq '.Host[]? | . as $host | .Port[]? | select(.Service.Name== "http") | $host.HostAddress.Address' | uniq -c
80-
```
81-
82-
```
83-
1 "192.168.1.1"
84-
1 "192.168.1.2"
85-
2 "192.168.1.3"
86-
```
87-
88-
In this case `192.168.1.3` has 2 http services running (for example on ports 80 and 8080)`.
89-
90-
Another example where it is needed to display only filtered ports:
91-
92-
```bash
93-
nmap-formatter json [nmap.xml] | jq '.Host[]?.Port[]? | select(.State.State == "filtered") | .PortID'
94-
```
95-
96-
Display host IP addresses that have filtered ports:
97-
98-
```bash
99-
nmap-formatter json [nmap.xml] | jq '.Host[]? | . as $host | .Port[]? | select(.State.State == "filtered") | .PortID | $host.HostAddress.Address'
100-
```
43+
More examples can be found on [Usage Wiki page](https://github.com/vdjagilev/nmap-formatter/wiki/Usage)
10144

10245
### Flags
10346

10447
* `-f, --file [filename]` outputs result to the file (by default output goes to STDOUT)
10548
* `--help` display help message
10649
* `--version` display version (also can be used: `./nmap-formatter version`)
10750

108-
#### Custom Options
109-
110-
Custom options can be used to deliver some information to the output (like user ID, or environment or hostname where scan has been performed). For this purpose there is `--x-opts` flag exists. It's possible to use multiple variables:
111-
112-
```bash
113-
nmap-formatter md nmap-file.xml --x-opts="Hostname=$HOST" --x-opts="Terminal=$TERM"
114-
```
115-
116-
The end result would contain those values after `Scan Summary` chapter. It would look something like this:
117-
118-
| Key | Value |
119-
| --- | ----- |
120-
| **Hostname** | `hostname123` |
121-
| **Terminal** | `xterm-256color` |
122-
123-
This command is applicable only in HTML & Markdown templates.
124-
125-
#### Output Options
126-
127-
##### HTML
128-
129-
| Flag | Description | Default | Example |
130-
| ---- | ----------- | ------- | --------------- |
131-
| `--html-skip-down-hosts` | Skip hosts that are down (offline/unable to connect), so they won't be shown in the output | `true` | `--html-skip-down-hosts=false` |
132-
| `--html-skip-summary` | Skip summary, it won't show various meta information about the scan | `false` | `--html-skip-summary=false` |
133-
| `--html-skip-traceroute` | Skip traceroute information (from the machine that ran nmap to the target) | `false` | `--html-skip-traceroute=false` |
134-
| `--html-skip-metrics` | Skip miscellaneous metrics information | `false` | `--html-skip-metrics=true` |
135-
| `--html-skip-port-scripts` | Skip port scripts output (nse-scripts) | `false` | `--html-skip-port-scripts=false` |
136-
| `--html-use-template` | Use specific HTML template instead of default one | `""` | `--html-use-template /path/to/template.html` |
137-
| `--html-dark-mode` | Dark mode in HTML template, enabled by default | `true` | `--html-dark-mode=false` |
138-
139-
##### Markdown
140-
141-
| Flag | Description | Default | Example |
142-
| ---- | ----------- | ------- | --------------- |
143-
| `--md-skip-down-hosts` | Skip hosts that are down (offline/unable to connect), so they won't be shown in the output | `true` | `--md-skip-down-hosts=false` |
144-
| `--md-skip-summary` | Skip summary, it won't show various meta information about the scan | `false` | `--md-skip-summary=false` |
145-
| `--md-skip-traceroute` | Skip traceroute information (from the machine that ran nmap to the target) | `false` | `--md-skip-traceroute=false` |
146-
| `--md-skip-metrics` | Skip miscellaneous metrics information | `false` | `--md-skip-metrics=true` |
147-
| `--md-skip-port-scripts` | Skip port scripts output (nse-scripts) | `false` | `--md-skip-port-scripts=false` |
148-
| `--md-use-template` | Use specific Markdown template instead of default one | `""` | `--md-use-template /path/to/template.md` |
149-
150-
##### CSV
151-
152-
| Flag | Description | Default | Example |
153-
| ---- | ----------- | ------- | --------------- |
154-
| `--csv-skip-down-hosts` | Skip hosts that are down (offline/unable to connect), so they won't be shown in the output | `true` | `--csv-skip-down-hosts=false` |
155-
156-
##### JSON
157-
158-
| Flag | Description | Default | Example |
159-
| ---- | ----------- | ------- | --------------- |
160-
| `--json-pretty` | Pretty print of JSON output | `false` | `--json-pretty=true` |
51+
It's also possible to change various output options. More examples on [Usage Wiki Page - Flags](https://github.com/vdjagilev/nmap-formatter/wiki/Usage#flags-and-output-options).
16152

16253
## Installation
16354

164-
### Using Go
55+
It's possible to install it using `go install` command
16556

16657
```
16758
go install github.com/vdjagilev/nmap-formatter@latest
16859
```
16960

170-
### Docker
171-
172-
No installation needed, just run `docker run`:
173-
174-
```
175-
docker run -v /path/to/xml/file.xml:/opt/file.xml ghcr.io/vdjagilev/nmap-formatter:latest json /opt/file.xml
176-
```
177-
178-
### Download Binary
179-
180-
Choose version from Release page and download it:
181-
182-
```
183-
curl https://github.com/vdjagilev/nmap-formatter/releases/download/v0.3.2/nmap-formatter-linux-amd64.tar.gz --output nmap-formatter.tar.gz -L
184-
tar -xzvf nmap-formatter.tar.gz
185-
./nmap-formatter --help
186-
```
187-
188-
### Compile
189-
190-
```
191-
git clone [email protected]:vdjagilev/nmap-formatter.git
192-
cd nmap-formatter
193-
go mod tidy
194-
go build
195-
# or
196-
go run . html path/to/nmap.xml
197-
```
61+
All other options can be found on [Installation Wiki page](https://github.com/vdjagilev/nmap-formatter/wiki/Installation).
19862

19963
## Example
20064

201-
Example of HTML generated output from (https://nmap.org/book/output-formats-xml-output.html)
202-
203-
```
204-
nmap-formatter html basic-example.xml
205-
```
206-
207-
![Basic HTML Example](docs/images/basic-example-html.png)
65+
Screenshots of various formats available [here](https://github.com/vdjagilev/nmap-formatter/wiki/Examples)
20866

20967
## Use as a library
21068

211-
How to parse nmap results using golang
212-
213-
```go
214-
package main
215-
216-
import (
217-
"encoding/xml"
218-
"os"
219-
220-
"github.com/vdjagilev/nmap-formatter/formatter"
221-
)
222-
223-
func main() {
224-
var nmap formatter.NMAPRun
225-
var config formatter.Config = formatter.Config{}
226-
227-
// Read XML file that was produced by nmap (with -oX option)
228-
content, err := os.ReadFile("example.xml")
229-
if err != nil {
230-
panic(err)
231-
}
232-
// Unmarshal XML and map structure(s) fields accordingly
233-
if err = xml.Unmarshal(content, &nmap); err != nil {
234-
panic(err)
235-
}
236-
237-
// Output data to console stdout
238-
// You can use any other io.Writer implementation
239-
// for example: os.OpenFile("file.json", os.O_CREATE|os.O_EXCL|os.O_WRONLY, os.ModePerm)
240-
config.Writer = os.Stdout
241-
// Formatting data to JSON, you can use:
242-
// CSVOutput, MarkdownOutput, HTMLOutput as well
243-
config.OutputFormat = formatter.JSONOutput
244-
245-
// Setting formatter data/options
246-
templateData := formatter.TemplateData{
247-
NMAPRun: nmap, // NMAP output data itself
248-
OutputOptions: formatter.OutputOptions{
249-
JSONOptions: formatter.JSONOutputOptions{
250-
PrettyPrint: true, // Additional option to prettify JSON
251-
},
252-
},
253-
}
254-
255-
// New formatter instance
256-
formatter := formatter.New(&config)
257-
if formatter == nil {
258-
// Not json/markdown/html/csv
259-
panic("wrong formatter provided")
260-
}
261-
262-
// Attempt to format the data
263-
if err = formatter.Format(&templateData, "" /* no template content for JSON */); err != nil {
264-
// html template could not be parsed or some other issue occured
265-
panic(err)
266-
}
267-
}
268-
269-
```
69+
Examples on how to use this project as a library in golang: [Use as a library Wiki page](https://github.com/vdjagilev/nmap-formatter/wiki/Use-as-a-library)

0 commit comments

Comments
 (0)