You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The **NAVV** (**N**etwork **A**rchitecture **V**erification and **V**alidation) tool creates a spreadsheet for network traffic analysis from PCAP data and Zeek logs, automating Zeek analysis of PCAP files, the collation of Zeek logs and the dissection of `conn.log` and `dns.log`to create a summary or network traffic in an XLSX-formatted spreadsheet. After manually updating the spreadsheet with names and color codes for network segments (by CIDR-formatted address groups) and hosts (by IP address), running the tool again will integrate these labels and color coding into the spreadsheet to aid in conducting an evaluation of the network traffic.
3
+
The **NAVV** (**N**etwork **A**rchitecture **V**erification and **V**alidation) tool creates a spreadsheet for network traffic analysis from PCAP data and Zeek logs, automating Zeek analysis of PCAP files and the collation of Zeek logs to create a summary or network traffic in an XLSX-formatted spreadsheet. After manually updating the spreadsheet with names and color codes for network segments (by CIDR-formatted address groups) and hosts (by IP address), running the tool again will integrate these labels and color coding into the spreadsheet to aid in conducting an evaluation of the network traffic.
4
4
5
+
*[Requirements](#Requirements)
5
6
*[Installation](#Installation)
6
-
*[Latest release](#InstallLatest)
7
-
*[Directly using `git`](#InstallGit)
8
-
*[External dependencies](#ExternalDeps)
9
-
*[Building and packaging](#Packaging)
7
+
*[Development](#Development)
8
+
*[Production](#Production)
10
9
*[Usage](#Usage)
11
-
*[Running NAVV](#Running)
12
-
*[Identifying network segments and hosts](#Analysis)
The NAVV tool is a Python script requiring `python3` and its `pip` tool. As installation of Python varies from platform to platform, please consult your operating system's documentation or the [python.org Wiki](https://wiki.python.org/moin/BeginnersGuide/Download) to install and configure Python 3 on your system.
22
+
- This project only works on Linux or MacOS environments
23
+
- Zeek must be installed: [Get Zeek](https://zeek.org/get-zeek/)
24
+
- Python version 3.10 or later
25
+
- As installation of Python varies from platform to platform, please refer to the [Python.org Wiki](https://wiki.python.org/moin/BeginnersGuide/Download) to install and configure Python on your system.
23
26
24
-
The recommended method for installing packages with `pip` is using [User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs) which installs to a user-specific location rather than system-wide. Usually this is done by running `pip` with the `--user` flag. It is generally *not* recommended to run `pip` with elevated/administrator/root privileges.
27
+
## Installation ##
25
28
26
-
### <aname="InstallLatest"></a>Latest release
29
+
### Development ###
27
30
28
-
Download the [latest NAVV release from GitHub](https://github.com/cisagov/network-architecture-verification-and-validation/releases/latest). Either of the `.whl`[built distribution](https://packaging.python.org/glossary/#term-Built-Distribution) or the `.tar.gz`[source archive](https://packaging.python.org/glossary/#term-Source-Archive) release artifacts should suffice.
Alternately, also using `pip`, to install the latest [release from PyPI](https://pypi.org/project/navv/):
45
+
If you would like to use the NAVV tool, its recommended you install it from PYPI
46
+
- Verify you have the Zeek tool installed
47
+
-[Install Zeek](https://zeek.org/get-zeek/)
48
+
- Install the project using `pip`
49
+
- The recommended method for installing packages with `pip` is using [User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs) which installs to a user-specific location rather than system-wide.
50
+
- install the latest version of NAVV
51
+
-`pip install -U navv`
52
+
- or install a specific version of NAVV
53
+
- example: `pip install -U navv==3.0.1`
40
54
41
-
```
42
-
python3 -m pip install -U navv
43
-
```
44
-
45
-
### <aname="InstallGit"></a>Directly using `git`
46
-
47
-
NAVV can be installed via `pip` using `git`:
55
+
Verify the NAVV tool has been installed by running `navv` in your console:
***openpyxl** library for interacting with Excel 2010 xlsx/xlsm ([Home](https://openpyxl.readthedocs.io/en/stable/), [PyPI](https://pypi.org/project/openpyxl/))
71
-
***tqdm** progress bar decorator library ([Home](https://tqdm.github.io/), [PyPI](https://pypi.org/project/tqdm/))
63
+
Options:
64
+
--version Show the version and exit.
65
+
-h, --help Show this message and exit.
72
66
73
-
The NAVV tool requires [Zeek](https://zeek.org/) to be installed with the `zeek` and `zeek-cut` utilities available in the `PATH`. Please consult the [Zeek manual](https://docs.zeek.org/en/current/install.html) for operating system-specifc instructions for installing and configuring Zeek. A NAVV [Docker](#Docker) image can be built which bundles both Zeek and the NAVV tool together.
74
-
75
-
### <aname="Packaging"></a>Building and packaging
76
-
77
-
PyPA's [build](https://packaging.python.org/key_projects/#build) module can be used to build and package the NAVV tool. At the command line, navigate to the directory containing the NAVV source code, then:
You will then see the packaged NAVV artifacts (the `.whl`[built distribution](https://packaging.python.org/glossary/#term-Built-Distribution) and the `.tar.gz`[source archive](https://packaging.python.org/glossary/#term-Source-Archive) files) in the `dist/` directory:
76
+
To run the NAVV tool in the CLI (Command Line Interface), Run the command: `navv generate`
115
77
78
+
Below are the available options and commands for `navv generate`:
116
79
```shell
117
-
$ ls -l ./dist/
118
-
total 672
119
-
-rw-r--r-- 1 build build 673878 Jun 15 22:05 navv-3.0.0-py3-none-any.whl
120
-
-rw-r--r-- 1 build build 11709 Jun 15 22:05 navv-3.0.0.tar.gz
80
+
Usage: navv generate [OPTIONS] CUSTOMER_NAME
81
+
82
+
Generate excel sheet.
83
+
84
+
Options:
85
+
-o, --output-dir TEXT Directory to place resultant analysis files in.
86
+
Defaults to current working directory.
87
+
-p, --pcap TEXT Path to pcap file. NAVV requires zeek logs or pcap.
88
+
If used, zeek will run on pcap to create new logs.
89
+
-z, --zeek-logs TEXT Path to store or contain zeek log files. Defaults to
90
+
current working directory.
91
+
-h, --help Show this message and exit.
121
92
```
122
93
123
-
You can then follow the same method from the [Latest Release](#InstallLatest) section to install the NAVV tool.
94
+
### Browser ###
124
95
125
-
Note that the resulting packaged NAVV artifacts do not contain the [external dependencies](#ExternalDeps) required to run the tool. Those Python libraries will be automatically [downloaded](https://pypi.org/) during the installation of the NAVV tool. If you are packaging the NAVV tool for distribution to a host without internet access, you will need to use `pip` to download the [external dependencies](#ExternalDeps) separately and install them prior to installing the NAVV tool.
96
+
To launch the NAVV tool in the browser, simply run: `navv launch`
Also, see [`docker/README.md`](./docker/README.md#BuildEnv) for a script which can be used to build and package the NAVV tool and its dependencies.
102
+
The user will have two options:
164
103
165
-
## <aname="Usage"></a>Usage
104
+
- Generate a New Analysis:
105
+
- Simply upload your PCAP file or a zipped file of your Zeek logs
106
+
- Click Run Analysis
107
+
- An excel sheet will be generated and downloaded via your browser
166
108
167
-
### <aname="Running"></a>Running NAVV
109
+
- Upload an Existing Analysis
110
+
- Modify your generated excel spreadsheet, See [Analysis](#Analysis)
111
+
- Upload your spreadsheet and your zipped Zeek logs file
168
112
169
-
The NAVV tool can be run with the command `python3 -m navv`, or simply `navv` if your `PATH` contains the installation location used by `pip` during [installation](#Installation).
113
+
### Analysis ###
170
114
171
-
Run the NAVV tool with `--help` to get a listing of its arguments:
-p PCAP, --pcap PCAP Path to pcap file. Will run zeek and output logs in cwd or --zeek-logs
187
-
-z ZEEK_LOGS, --zeek-logs ZEEK_LOGS
188
-
Directory containing log files
189
-
```
190
-
191
-
The NAVV tool will accept as input a PCAP file, in which case it will run `zeek` to generate the Zeek log files containing the metadata about the network traffic; or, a directory containing Zeek logs from a previous analysis.
192
-
193
-
For example:
194
-
195
-
```shell
196
-
analyst@host tmp> ll
197
-
total 178M
198
-
drwxrwxr-x 2 analyst analyst 6 Jun 15 22:36 ACME_logs
199
-
-rw-r--r-- 1 analyst analyst 178M Jun 15 22:35 ACME.pcap
-rw-rw-r-- 1 analyst analyst 150 Jun 15 22:36 ACME_dns_data.pkl
234
-
-rw-rw-r-- 1 analyst analyst 203483 Jun 15 22:36 ACME_network_analysis.xlsx
235
-
```
236
-
237
-
As the example illustrates, the NAVV tool generated `.pkl` and `.xlsx` files as a result of the processing of `ACME.pcap`.
238
-
239
-
### <a name="Analysis"></a>Identifying network segments and hosts
115
+
Identifying network segments and hosts
240
116
241
117
Adding information about network segments and/or inventory can assist in packet capture analysis. Open the NAVV-generated `.xlsx` file and navigate to the `Segments` tab. Enter the relevant network segments and choose background colors for the corresponding cells. For example:
242
118
@@ -246,11 +122,11 @@ Save your changes and re-run the NAVV tool with the `-z` option on the directory
246
122
247
123
When available, the NAVV tool will use responses for queries found in Zeek's `dns.log` file to populate the `Src_Desc` and `Dest_Desc` fields in the `Analysis` tab. When DNS information is not available, it is possible to provide this information manually in the `Inventory` tab. Note that color formatting from the `Inventory` tab is applied **after** that from the `Segments` tab. Again, saving changes to the spreadsheet file and re-running the NAVV tool with the `-z` option will update the spreadsheet with the new inventory information and color formatting.
248
124
249
-
## <a name="Docker"></a>Docker
125
+
## Docker ##
250
126
251
127
See [`docker/README.md`](./docker/README.md) for setup and instructions for running the NAVV tool in Docker.
252
128
253
-
## <a name="Footer"></a>Copyright
129
+
## Copyright ##
254
130
255
131
[NAVV](https://github.com/cisagov/network-architecture-verification-and-validation) is Copyright 2023 Battelle Energy Alliance, LLC, licensed under the BSD-3 Clause License.
256
132
@@ -261,7 +137,7 @@ Developers, by contributing to this software project, you are agreeing to the fo
261
137
* You agree your contributions are submitted under the BSD 3-Clause license.
262
138
* You represent you are authorized to make the contributions and grant the license. If your employer has rights to intellectual property that includes your contributions, you represent that you have received permission to make contributions and grant the required license on behalf of that employer.
263
139
264
-
## Other software
140
+
## Other software ##
265
141
266
142
Idaho National Laboratory is a cutting edge research facility which is constantly producing high quality research and software. Feel free to take a look at our other software and scientific offerings at:
267
143
@@ -270,7 +146,9 @@ Idaho National Laboratory is a cutting edge research facility which is constantl
270
146
*[Raw Experiment Open Source Software](https://github.com/IdahoLabResearch)
271
147
*[Unsupported Open Source Software](https://github.com/IdahoLabCuttingBoard)
272
148
273
-
## <a name="Contact"></a>Contact information of maintainer(s):
0 commit comments