An Introduction to OWASP Amass 4 - Part 9 - Visualizing with oam_viz
The OWASP Amass project is an open-source, actively developed security tool with extensive community support that focuses on information gathering and reconnaissance. It helps security researchers and penetration testers discover and map the attack surface of their target networks by using a variety of data sources. Whether you are a penetration tester, an auditor, a security researcher or the CISO/IT manager, you have several valid reasons for mapping out the external attack surface of an organisation. This process is also referred to as reconnaissance or information gathering.
Version 4 is a major revision of Amass. If you are familiar with earlier versions then you will need to change your approach to understand how it is organized and how this "framework" works.
In this instalment in our series on OWASP Amass version 4 we introduce the components of the ecosystem that allow us to view and analyze the assets discovered during enumeration. This is part 9 of the series and the second post in extracting and analyzing results.
Part 1, is an introduction to the Amass GitHub,
Part 2 discusses the data model and the approach to configuration in your workflow, and
Part 3 explains a Postgres database setup,
Part 4 explains installation of the CLI tool.
In Part 5 we introduced configuration and had our first run of the
amass enumcommand.Part 6 looked at some issues with data sources.
Part 7 spent some quality time with in depth enumeration details.
Part 8 Introduced OAM Tools and looked specifically at oam_subs.
Overview
The oamsubs command line tool in the previous post provided an opportunity to looks at asset findings from a prior enumeration. This enabled us to extract domain, ASN, and IP information. We could also forward these findings to downstream tools for further analysis. But there are other tools in addition to oamsubs in the OAM Tools repository. This post is going to focus on using oam_viz to visualize asset information.
The oamsubs tool is great for getting raw text information about ASNs, IPs, and domains. But sometimes we need a graphic interpretation of the information to show connections and associations. This is where oam_viz helps.
OAM Tools
As a brief review, OAM Tools is a suite of command line tools in which we will cover the three that currently exists.
oam_subs, Analyze collected OAM assets
oam_track, Analyze collected OAM data to identify newly discovered assets
oam_viz, Analyze collected OAM data to generate files renderable as graph visualizations
If you have no already installed the OAM Tools components then the previous post already covers this. Note: that you will need to have a Go environment setup (which is out of scope for this post). But to quickly to install all commands from the repo you can:
Once installation is complete the three binaries should be available in $GOPATH/bin. Here is the example on my system.
user@host:~# which oam_viz /usr/local/go/bin/oam_viz
Using oam_viz
With the oam_tools installed we can now start to review some of our results from previous work. A quick look at the help information provided shows us its current capabilities:
user@host:~# oam_viz -help
Usage: oam_viz -d3|-dot|-gexf [options] -d domain
-config string
Path to the YAML configuration file
-d value
Domain names separated by commas (can be used multiple times)
-d3
Generate the D3 v4 force simulation HTML file
-df string
Path to a file providing registered domain names
-dir string
Path to the directory containing the graph database
-dot
Generate the DOT output file
-gexf
Generate the Gephi Graph Exchange XML Format (GEXF) file
-h Show the program usage message
-help
Show the program usage message
-nocolor
Disable colorized output
-o string
Path to the directory for output files being generated
-oA string
Path prefix used for naming all output files
-silent
Disable all output during execution
-since string
Include only assets validated after (format: 01/02 15:04:05 2006 MST)We will also continue to use the configuration file we have established in a prior post with the target scope, database, and datasources defined. Below we are going to display the results of the enumeration. This retrieves all the details about our target domain from the database. Its a quick view of what has been found.
-config <path to our YAML configuration file>, identify a configuration file to use for scope and database details.
D3 v4 Force Simulation
This sounds more like a new VR game than a visualization, but it is a powerful tool using version 4 of the D3.js library. The D3.js library is a powerful JavaScript library for creating data visualizations in the web, often by manipulating the Document Object Model (DOM) based on data. In this case, the data is domain and subdomain information collected during the enumeration phase and stored in our database identified in our configuration YAML file.
By using the -d3 option we will generate an HTML file which we can obviously load in our browser. To do this the command we will use is:
user@host:$ oam_viz -config ./amass-config-owasp.yaml -d3 -d owasp.org -o ./
The other options we have provided beside the configuration and specify generating a D3 document are -d for the domains to display and -o for the path to the directory to place the output html file. Once complete, the output file will be named amass.html. I did not need to specify -dir (path to directory containing the graph database) because our configuration used the Postgres database and is specified in the configuration file identified by -config.
We can also name the output html file by using the -oA comand such as:
oam_viz -config ./amass-config-owasp.yaml -d3 -d owasp.org -o ./ -oA someprefix
This will generate an output html file with the name someprefix.html.
Below is an example display of the html file as rendered by a browser.
D3 Rendering of Enumerated Asset information
Once I load the file into a browser I am shown an interactive display of the topology of the domain as found during enumeration. I can use my mouse to hover over elements to display their values and rearrange some of the elements.
DOT Output
A DOT output file is a plain text file that represents graphs in the DOT language, which is a graph description language. DOT is part of the Graphviz software package, which is widely used for visualizing graphs and networks. The file typically has a .dot or .gv file extension. However despite generating a dot file we have yet to have a useful rendering to date. If we have success with this format we will update this blog.
Gephi Graph Exchange
Using -gexf generates a file in the Gephi Graph Exchange XML Format (GEXF). Gephi Graph Exchange XML Format (say that three times fast) is an XML-based file format designed to describe complex network structures, which include nodes (vertices) and edges (connections between nodes). This format is primarily used with Gephi, an open-source network analysis and visualization software. GEXF files are used to store and exchange graph data, allowing for the preservation of network structures along with their metadata, attributes, and dynamic properties.
As with DOT, you will need to have specialized software to load the output. You would probably choose this format because Gephi is already part of your workflow. You can download the open source Gephi but it an education beyond the scope of this post.
Conclusion
Visualization is great and if do not have installed or experience with specialized tools such as Graphviz or Gephi then the simplest approach is to use the D3 format and view it in a browser. Its uncomplicated that way. Otherwise, if you already have established a workflow with the other tools then oam_viz can accommodate you.
Read the fine Manual
The OAM Tools repository has some documentation that is worth your while to review. There is a User’s Guide that lists all the options and a more Comprehensive Guide that goes into more detail.
Wrap Up
In this instalment we introduced the OAM Tool oam_viz for visualization and we looked at the three formats that it can output. The simplest workflow was generating a D3 HTML file and opening it in a browser.
