Skip to content

Usage

Jump to bottom
Dustin Born edited this page Apr 10, 2020 · 13 revisions

Introduction

AVAIN was originally constructed for the vulnerability assessment of computer networks or individual machines therein. As such, the the final output is a vulnerability score that serves as a security indicator for the assessed network. To construct such a score, AVAIN has to do a vulnerability analysis or penetration test first. AVAIN saves all of the intermediate results it and its modules gather and construct. Therefore security experts and penetration testers can look at all of these results to get a good understanding of the properties and security risks that the assessed machines and their running services have.

After AVAIN was successfully installed, it can be invoked from the command line from anywhere on the system by simply calling it: avain. The most basic command to run would be the assessment of a single host. This can be achieved like so:

avain -n 192.168.0.1

Once this command is run, AVAIN starts the vulnerability analysis / penetration test of the host 192.168.0.1 and will output the results to a directory of the following form: avain_output-{timestamp}, where {timestamp} represents the datetime timestamp when AVAIN was invoked. The structure of the output directory is explained on a separate wiki page.
Important: AVAIN can only be run once at a time, multiple instances at the same time can lead to consistency issues.

Program Arguments

If AVAIN is invoked without any arguments, the usage information is displayed:

usage: avain [-h] [-n NETWORKS [NETWORKS ...]] [-nL NETWORK_LIST] [-uM]
             [-i INPUT] [-sR SCAN_RESULTS [SCAN_RESULTS ...]]
             [-vS VULNERABILITY_SCORES [VULNERABILITY_SCORES ...]]
             [-wM WEBSERVER_MAP [WEBSERVER_MAP ...]] [-c CONFIG] [-o OUTPUT]
             [-p PORTS] [-sN] [-v] [-q]
avain: error: at least one of the following arguments is required: -n/--network, -nL/--network-list,
-uD/--update-modules, -i/--input or any one of [-sR/--scan-results, -vS/--vulnerability-scores,
-wM/--webserver-map]

The different program arguments are described as follows:

  • -h / --help: Prints AVAIN's help message and exits.
  • -n / --networks: Specify one or more networks to scan. A network can be a single IP, an IP range expression, a wildcard expression or a CIDR expression. This is identical to Nmap's concept of a network expression (see here "Specification and Examples"). To specify multiple networks, separate them with a space.
  • -nL / --network-list: Specify a file containing networks to include into or exclude from the scan. The file has to be a text file containing one network expression per line. If a network expression is prefixed with a + or has no prefix at all, the network is included into the scan. If a network expression is prefixed with a -, the network is excluded from the scan.
  • -uM / --update-modules: A flag that signals AVAIN to update all of its modules.
  • -i / --input: Specify a previous AVAIN output folder as input to reuse all aggregated results therein.
  • -c / --config: Specify a custom configuration file or profile for AVAIN to use. The specified configuration overwrites AVAIN's default configuration.
  • -o / --output: Specify the name of the output directory. If the directory does not exist, AVAIN creates it.
  • -p / --ports: Set the ports that should be scanned on every host. As of now, it is not possible to set a custom setting per host. The port expressions are very similar to Nmap's port expressions (see here). Multiple port expressions are separated by a comma.
  • -sN / --separate-networks: Instruct AVAIN to operate in separate networks mode meaning that all specified networks are assessed and scored independently. As a result, in the end there will be multiple score that represents the security levels of every specified network independently. Logically, using this flag when only one host / network is specified has no effect.
  • -sR / --scan-results: Have AVAIN include additional scan results from one or more JSON files.
  • -vS / --vulnerability-scores: Have AVAIN include additional vulnerability score results from one or more JSON files.
  • -wM / --webserver-map: Have AVAIN include additional webserver map results from one or more JSON files.
  • -v / --verbose: A flag to make AVAIN's output verbose (AVAIN is verbose by default).
  • -q / --quiet: A flag to make AVAIN's output non verbose / quiet.

Out of the above arguments, required is at least one of -n/--network, -nL/--network-list, -uM/--update-modules, -i/--input or any one of [-sR/--scan-results, -vS/--vulnerability-scores, -wM/--webserver-map].

Once called, AVAIN runs automatically without the need for further user interaction. If the user specified a certain output directory, the results are put into that directory. Otherwise they are put into a directory named similarly to avain_output-20180824_235333, where the numbers are a (unique) timestamp of the current day and time.

Note: As mentioned in Getting Started, on the first run, you may have to allow some software to run, or "allow incoming network connections" for the crawler module, because it utilizes a local Unix socket.

Examples

Three examples of how you can call AVAIN:

  • avain -n 10.0.42.* 192.168.0.1-150 -sN -c config/someconfig.cfg -v
  • avain -n 192.168.0.* -uM -p T:80,U:53 -o http_dns_sec
  • avain -sR path_to_sr_1 path_to_sr_2 -o network_analysis
Clone this wiki locally