An Introduction to OWASP Amass 4 - Part 5 - Configuration
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 focus on the configuration to use of the command line interface (CLI) tool in the ecosystem. This is part 5 of the series. 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, and Part 4 explains installation of the CLI tool.
Overview
In the previous release, Amass 3 used a single INI Key/Value pair configuration file. This covered both data sources and target scope. Amass 4 improves configuration flexibility by separating scope configuration and data sources in two different files. In addition, both files use a YAML format.
For those with the legacy INI file the oam_i2y tool converts the Amass 3 INI configuration file into two YAML files that can be used by the new framework. Consult the OAM Configuration Repository for more information.
Data Sources
In the Amass ecosystem, “data sources” refers to the online resources is performs queries for your target. This will include Censys, BinaryEdge, AlienVault, VirusTotal, and others. Amass provides a default file to get you started here. When you review this file you will notice the need to API Keys to data sources, therefore be advised to not share your updated file containing your API Keys in public locations.
You can run Amass without any configured API keys. However your results will improve with each configured data source.
To keep things organized we will store our data sources configuration file in $HOME/.config/amass. If you have been following along with our Ubuntu install then you will need to create this directory as the Amass CLI install will not create this automatically for us.
┌──(user㉿kanga)-[~]
└─$ cd $HOME/.config
┌──(user㉿kanga)-[~/.config]
└─$ cd amass
cd: no such file or directory: amass
┌──(user㉿kanga)-[~/.config]
└─$ mkdir amass
┌──(user㉿kanga)-[~/.config]
└─$ cd amass
┌──(user㉿kanga)-[~/.config/amass]Now I am going to pull down the data sources file from the repository.
┌──(user㉿kanga)-[~/.config/amass]
└─$ wget https://raw.githubusercontent.com/owasp-amass/amass/master/examples/datasources.yaml
--2024-07-06 11:24:29-- https://github.com/owasp-amass/amass/blob/master/examples/datasources.yaml
Resolving github.com (github.com)... 140.82.112.4
Connecting to github.com (github.com)|140.82.112.4|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: unspecified [text/html]
Saving to: ‘datasources.yaml’
datasources.yaml [ <=> ] 175.97K --.-KB/s in 0.07s
2024-07-06 11:24:29 (2.60 MB/s) - ‘datasources.yaml’ saved [180198]
┌──(user㉿kanga)-[~/.config/amass]
└─$ ls -la
total 184
drwxrwxr-x 2 user user 4096 Jul 6 11:24 .
drwx------ 7 user user 4096 Jul 6 11:22 ..
-rw-rw-r-- 1 user user 180198 Jul 6 11:24 datasources.yamlNow you can edit this file to add your API keys. Amass will run without API keys but your results will improve with API keys from the sources lists here. In a future blog post we will discuss data sources further.
Note that the Amass 4 Framework DOES NOT accept the data sources yaml file on the command line. Only the configuration file (next section).
We will use the configuration file to specify our data sources file. This means that for a specific engagement, we can specify different data sources files.
The Configuration File
Amass looks for this file in predefined locations or you can specify a location using the -config flag or the AMASS_CONFIG environment variable. Otherwise, for linux it will search in the following locations.
$XDG_CONFIG_HOME/amass/config.yaml$HOME/.config/amass/config.yamlor/etc/amass/config.yaml
Your approach to where you store your Amass configuration files will depend on your workflow.
For example, consider the case where you have several engagements. How can you keep the data and information separate so there is no inadvertent leakage between clients when you report. In this case we could create a directory for each client and within have a separate Amass configuration file.
For our example we will use $HOME/.config/amass/ to store our configuration files. However we will identify different targets in the file name. For example, amass-config-target1.yaml, and so on. Then, when we execute an Amass CLI command, we will specify the configuration file to use with the -config flag. Such as:
amass enum -config $HOME/.config/amass/amass-config-target.yamlThe configuration file syntax is defined here. Briefly, you define two root sections, scope and options.
For the scope section, you are defining the scope of your target. And within you can use a variety of element to define the scope including:
domains. DNS Domain names of targets in scope.
ips. A comma separated list of IPs or a hyphenated range.
asns. Autonomous system numbers.
ports. Ports to reach out to for active reconnaissance.
cidrs. CIDR notation IP ranges in scope.
blacklist. Subdomains to be blacklisted or out of scope.
The options section permit us to tune our research and provides considerable flexibility. For this blog post we are going to look at two specific entries:
datasources. The file that contains the data source configuration (previous section). This path is relative to the location of the configuration file.
database. The database where the information will be stored. This gives us the ability to compartmentalize results as explained in previous blog postings. It requires the format of
scheme://username:password@host:port/database_name?options=works.
Of course there are more options but those can be covered in a later blog post.
Lets consider now a basic configuration example:
scope:
domains: # domain names to be in scope
- owasp.org
ports: # ports to be used when actively reaching a service
- 80
- 443
options:
datasources: "/home/user/.config/amass/datasources.yaml" # the file path that will point to the data source configuration
database: "postgres://<dbuser>:<dbpassword>@127.0.0.1:5432/assetdb?testing=works" # databases URI to be used when adding entriesIn the above example we are going to use the owasp.org domain as our target and for any active recon work it will look at ports 80 and 443. We specify a data source file which will contain all our API keys for the data sources we have accounts with. Finally, we specify where Amass will store all its asset data. Ideally here, my configuration file and the target database will be in sync by name to compartmentalize asset information between engagements.
Ensure that you change the elements for your system, for example dbuser and password, linux user name, etc.
We are now ready to stand behind the lead shield and run our first test.
Finally it should be noted, that although the configuration file is great to manage our workflow, be advised that any command line parameters take precedence over configuration file entries.
The Lead Shield
With our datasources and configuration file ready, and our database container running lets run our first test.
WARNING: Specific to active reconnaissance tests, ensure you have permission to access the targets you are performing active reconnaissance on.
Since Jeff Foley, the creator of Amass is always using owasp.org in his examples we will use the owasp.org domain. The command below will perform a subdomain enumeration on the target scope.
┌──(user㉿kanga)-[~/.config/amass]
└─$ amass enum -config ./amass-config-owasp.yaml
cornucopia.owasp.org (FQDN) --> a_record --> 172.67.10.39 (IPAddress)
cornucopia.owasp.org (FQDN) --> a_record --> 104.22.26.77 (IPAddress)
cornucopia.owasp.org (FQDN) --> a_record --> 104.22.27.77 (IPAddress)
cornucopia.owasp.org (FQDN) --> aaaa_record --> 2606:4700:10::6816:1b4d (IPAddress)
cornucopia.owasp.org (FQDN) --> aaaa_record --> 2606:4700:10::6816:1a4d (IPAddress)
cornucopia.owasp.org (FQDN) --> aaaa_record --> 2606:4700:10::ac43:a27 (IPAddress)
owasp.org (FQDN) --> ns_record --> west.ns.cloudflare.com (FQDN)
owasp.org (FQDN) --> ns_record --> fay.ns.cloudflare.com (FQDN)
------------------8<-----------------------------------What you should then see is console output showing Amass findings.
Wrap Up
In this instalment we covered configuring the Amass CLI tool on an Ubuntu server. We discussed the organization of configuration between scope and datasources and provided a simple example of the configuration file. In the next instalment we will discuss more options to improve our scans.
