diff --git a/doc/user_guide.md b/doc/user_guide.md index dca1f5e56..e5fe6aaf7 100644 --- a/doc/user_guide.md +++ b/doc/user_guide.md @@ -53,7 +53,17 @@ The amass tool has several subcommands shown below for handling your Internet ex | track | Compare results of enumerations against common target organizations | | db | Manage the graph databases storing the enumeration results | -Each subcommand has its own arguments that are shown in the following sections. +All subcommands have some default global arguments that can be seen below. + +| Flag | Description | Example | +|------|-------------|---------| +| -h/-help | Show the program usage message | amass subcommand -h | +| -config | Path to the INI configuration file | amass subcommand -config config.ini | +| -dir | Path to the directory containing the graph database | amass subcommand -dir PATH -d example.com | +| -nocolor | Disable colorized output | amass subcommand -nocolor -d example.com | +| -silent | Disable all output during execution | amass subcommand -silent -json out.json -d example.com | + +Each subcommand's own arguments are shown in the following sections. ### The 'intel' Subcommand @@ -65,11 +75,9 @@ The intel subcommand can help you discover additional root domain names associat | -addr | IPs and ranges (192.168.1.1-254) separated by commas | amass intel -addr 192.168.2.1-64 | | -asn | ASNs separated by commas (can be used multiple times) | amass intel -asn 13374,14618 | | -cidr | CIDRs separated by commas (can be used multiple times) | amass intel -cidr 104.154.0.0/15 | -| -config | Path to the INI configuration file | amass intel -config config.ini | | -d | Domain names separated by commas (can be used multiple times) | amass intel -whois -d example.com | | -demo | Censor output to make it suitable for demonstrations | amass intel -demo -whois -d example.com | | -df | Path to a file providing root domain names | amass intel -whois -df domains.txt | -| -dir | Path to the directory containing the graph database | amass intel -dir PATH -cidr 104.154.0.0/15 | | -ef | Path to a file providing data sources to exclude | amass intel -whois -ef exclude.txt -d example.com | | -exclude | Data source names separated by commas to be excluded | amass intel -whois -exclude crtsh -d example.com | | -if | Path to a file providing data sources to include | amass intel -whois -if include.txt -d example.com | @@ -87,6 +95,7 @@ The intel subcommand can help you discover additional root domain names associat | -rf | Path to a file providing preferred DNS resolvers | amass intel -rf data/resolvers.txt -whois -d example.com | | -src | Print data sources for the discovered names | amass intel -src -whois -d example.com | | -timeout | Number of minutes to execute the enumeration | amass intel -timeout 30 -d example.com | +| -v | Output status / debug / troubleshooting info | amass intel -v -whois -d example.com | | -whois | All discovered domains are run through reverse whois | amass intel -whois -d example.com | ### The 'enum' Subcommand @@ -96,18 +105,20 @@ This subcommand will perform DNS enumeration and network mapping while populatin | Flag | Description | Example | |------|-------------|---------| | -active | Enable active recon methods | amass enum -active -d example.com -p 80,443,8080 | +| -alts | Enable generation of altered names | amass enum -alts -d example.com | | -aw | Path to a different wordlist file for alterations | amass enum -aw PATH -d example.com | +| -awm | "hashcat-style" wordlist masks for name alterations | amass enum -awm dev?d -d example.com | | -bl | Blacklist of subdomain names that will not be investigated | amass enum -bl blah.example.com -d example.com | | -blf | Path to a file providing blacklisted subdomains | amass enum -blf data/blacklist.txt -d example.com | | -brute | Perform brute force subdomain enumeration | amass enum -brute -d example.com | -| -config | Path to the INI configuration file | amass enum -config config.ini | | -d | Domain names separated by commas (can be used multiple times) | amass enum -d example.com | | -demo | Censor output to make it suitable for demonstrations | amass enum -demo -d example.com | | -df | Path to a file providing root domain names | amass enum -df domains.txt | -| -dir | Path to the directory containing the graph database | amass enum -dir PATH -d example.com | +| -dns-qps | Maximum number of DNS queries per second across all resolvers | amass enum -dns-qps 200 -d example.com | | -ef | Path to a file providing data sources to exclude | amass enum -ef exclude.txt -d example.com | | -exclude | Data source names separated by commas to be excluded | amass enum -exclude crtsh -d example.com | | -if | Path to a file providing data sources to include | amass enum -if include.txt -d example.com | +| -iface | Provide the network interface to send traffic through | amass enum -iface en0 -d example.com | | -include | Data source names separated by commas to be included | amass enum -include crtsh -d example.com | | -ip | Show the IP addresses for discovered names | amass enum -ip -d example.com | | -ipv4 | Show the IPv4 addresses for discovered names | amass enum -ipv4 -d example.com | @@ -115,26 +126,27 @@ This subcommand will perform DNS enumeration and network mapping while populatin | -json | Path to the JSON output file | amass enum -json out.json -d example.com | | -list | Print the names of all available data sources | amass enum -list | | -log | Path to the log file where errors will be written | amass enum -log amass.log -d example.com | +| -max-depth | Maximum number of subdomain labels for brute forcing | amass enum -brute -max-depth 3 -d example.com | | -max-dns-queries | Deprecated flag to be replaced by dns-qps in version 4.0 | amass enum -max-dns-queries 200 -d example.com | -| -dns-qps | Maximum number of DNS queries per second across all resolvers | amass enum -dns-qps 200 -d example.com | -| -rqps | Maximum number of DNS queries per second for each untrusted resolver | amass enum -rqps 10 -d example.com | -| -trqps | Maximum number of DNS queries per second for each trusted resolver | amass enum -trqps 20 -d example.com | | -min-for-recursive | Subdomain labels seen before recursive brute forcing (Default: 1) | amass enum -brute -min-for-recursive 3 -d example.com | -| -max-depth | Maximum number of subdomain labels for brute forcing | amass enum -brute -max-depth 3 -d example.com | | -nf | Path to a file providing already known subdomain names (from other tools/sources) | amass enum -nf names.txt -d example.com | -| -noalts | Disable generation of altered names | amass enum -noalts -d example.com | | -norecursive | Turn off recursive brute forcing | amass enum -brute -norecursive -d example.com | | -o | Path to the text output file | amass enum -o out.txt -d example.com | | -oA | Path prefix used for naming all output files | amass enum -oA amass_scan -d example.com | -| -passive | A purely passive mode of execution | amass enum --passive -d example.com | | -p | Ports separated by commas (default: 443) | amass enum -d example.com -p 443,8080 | +| -passive | A purely passive mode of execution | amass enum --passive -d example.com | | -r | IP addresses of untrusted DNS resolvers (can be used multiple times) | amass enum -r 8.8.8.8,1.1.1.1 -d example.com | -| -tr | IP addresses of trusted DNS resolvers (can be used multiple times) | amass enum -tr 8.8.8.8,1.1.1.1 -d example.com | | -rf | Path to a file providing untrusted DNS resolvers | amass enum -rf data/resolvers.txt -d example.com | -| -trf | Path to a file providing trusted DNS resolvers | amass enum -trf data/trusted.txt -d example.com | +| -rqps | Maximum number of DNS queries per second for each untrusted resolver | amass enum -rqps 10 -d example.com | +| -scripts | Path to a directory containing ADS scripts | amass enum -scripts PATH -d example.com | | -src | Print data sources for the discovered names | amass enum -src -d example.com | | -timeout | Number of minutes to execute the enumeration | amass enum -timeout 30 -d example.com | -| -w | Path to a different wordlist file | amass enum -brute -w wordlist.txt -d example.com | +| -tr | IP addresses of trusted DNS resolvers (can be used multiple times) | amass enum -tr 8.8.8.8,1.1.1.1 -d example.com | +| -trf | Path to a file providing trusted DNS resolvers | amass enum -trf data/trusted.txt -d example.com | +| -trqps | Maximum number of DNS queries per second for each trusted resolver | amass enum -trqps 20 -d example.com | +| -v | Output status / debug / troubleshooting info | amass enum -v -d example.com | +| -w | Path to a different wordlist file for brute forcing | amass enum -brute -w wordlist.txt -d example.com | +| -wm | "hashcat-style" wordlist masks for DNS brute forcing | amass enum -brute -wm ?l?l -d example.com | ### The 'viz' Subcommand @@ -146,19 +158,17 @@ Switches for outputting the DNS and infrastructure findings as a network graph: | Flag | Description | Example | |------|-------------|---------| -| -config | Path to the INI configuration file | amass viz -config config.ini -d3 | | -d | Domain names separated by commas (can be used multiple times) | amass viz -d3 -d example.com | | -d3 | Output a D3.js v4 force simulation HTML file | amass viz -d3 -d example.com | | -df | Path to a file providing root domain names | amass viz -d3 -df domains.txt | -| -dir | Path to the directory containing the graph database | amass viz -d3 -dir PATH -d example.com | +| -dot | Generate the DOT output file | amass viz -dot -d example.com | | -enum | Identify an enumeration via an index from the db listing | amass viz -enum 1 -d3 -d example.com | -| -o | Path to a pre-existing directory that will hold output files | amass viz -d3 -o OUTPATH -d example.com | -| -oA | Prefix used for naming all output files | amass viz -d3 -oA example -d example.com | | -gexf | Output to Graph Exchange XML Format (GEXF) | amass viz -gexf -d example.com | | -graphistry | Output Graphistry JSON | amass viz -graphistry -d example.com | | -i | Path to the Amass data operations JSON input file | amass viz -d3 -d example.com | | -maltego | Output a Maltego Graph Table CSV file | amass viz -maltego -d example.com | - +| -o | Path to a pre-existing directory that will hold output files | amass viz -d3 -o OUTPATH -d example.com | +| -oA | Prefix used for naming all output files | amass viz -d3 -oA example -d example.com | ### The 'track' Subcommand @@ -166,10 +176,8 @@ Shows differences between enumerations that included the same target(s) for moni | Flag | Description | Example | |------|-------------|---------| -| -config | Path to the INI configuration file | amass track -config config.ini | | -d | Domain names separated by commas (can be used multiple times) | amass track -d example.com | | -df | Path to a file providing root domain names | amass track -df domains.txt | -| -dir | Path to the directory containing the graph database | amass track -dir PATH | | -history | Show the difference between all enumeration pairs | amass track -history | | -last | The number of recent enumerations to include in the tracking | amass track -last NUM | | -since | Exclude all enumerations before a specified date (format: 01/02 15:04:05 2006 MST) | amass track -since DATE | @@ -180,23 +188,18 @@ Performs viewing and manipulation of the graph database. This subcommand only le | Flag | Description | Example | |------|-------------|---------| -| -config | Path to the INI configuration file | amass db -config config.ini | | -d | Domain names separated by commas (can be used multiple times) | amass db -d example.com | | -demo | Censor output to make it suitable for demonstrations | amass db -demo -d example.com | | -df | Path to a file providing root domain names | amass db -df domains.txt | -| -dir | Path to the directory containing the graph database | amass db -dir PATH | | -enum | Identify an enumeration via an index from the listing | amass db -enum 1 -show | -| -import | Import an Amass data operations JSON file to the graph database | amass db -import PATH | | -ip | Show the IP addresses for discovered names | amass db -show -ip -d example.com | | -ipv4 | Show the IPv4 addresses for discovered names | amass db -show -ipv4 -d example.com | | -ipv6 | Show the IPv6 addresses for discovered names | amass db -show -ipv6 -d example.com | | -json | Path to the JSON output file or '-' | amass db -names -silent -json out.json -d example.com | | -list | Print enumerations in the database and filter on domains specified | amass db -list | | -names | Print just discovered names | amass db -names -d example.com | -| -nocolor | Disable colorized output | amass db -names -nocolor -d example.com | | -o | Path to the text output file | amass db -names -o out.txt -d example.com | | -show | Print the results for the enumeration index + domains provided | amass db -show | -| -silent | Disable all output during execution | amass db -names -silent -json out.json -d example.com | | -src | Print data sources for the discovered names | amass db -show -src -d example.com | | -summary | Print just ASN table summary | amass db -summary -d example.com | @@ -234,48 +237,50 @@ Note that these locations are based on the [output directory](#the-output-direct | output_directory | The directory that stores the graph database and other output files | | maximum_dns_queries | The maximum number of concurrent DNS queries that can be performed | -### The network_settings Section +### The `resolvers` Section | Option | Description | |--------|-------------| -| address | IP address or range (e.g. a.b.c.10-245) that is in scope | -| asn | ASN that is in scope | -| cidr | CIDR (e.g. 192.168.1.0/24) that is in scope | -| port | Specifies a port to be used when actively pulling TLS certificates | +| resolver | The IP address of a DNS resolver and used globally by the amass package | -### The domains Section +### The `scope` Section | Option | Description | |--------|-------------| -| domain | A root DNS domain name to be added to the enumeration scope | +| address | IP address or range (e.g. a.b.c.10-245) that is in scope | +| asn | ASN that is in scope | +| cidr | CIDR (e.g. 192.168.1.0/24) that is in scope | +| port | Specifies a port to be used when actively pulling TLS certificates or crawling | -### The resolvers Section +#### The `scope.domains` Section | Option | Description | |--------|-------------| -| resolver | The IP address of a DNS resolver and used globally by the amass package | +| domain | A root DNS domain name to be added to the enumeration scope | -### The blacklisted Section +#### The `scope.blacklisted` Section | Option | Description | |--------|-------------| | subdomain | A DNS subdomain name to be considered out of scope during the enumeration | -### The disabled_data_sources Section +### The `graphdbs` Section + +#### The `graphdbs.postgres` Section | Option | Description | |--------|-------------| -| data_source | One of the Amass data sources that is **not** to be used during the enumeration | +| primary | When set to true, the graph database is specified as the primary db | +| url | URL in the form of "postgres://[username:password@]host[:port]/database-name?sslmode=disable" where Amass will connect to a PostgreSQL database | +| options | Additional PostgreSQL database options | -### The gremlin Section +#### The `graphdbs.mysql` Section | Option | Description | |--------|-------------| -| url | URL in the form of "ws://host:port" where Amass will connect to a TinkerPop database | -| username | User of the TinkerPop database server that can access the Amass graph database | -| password | Valid password for the user identified by the 'username' option | +| url | URL in the form of "[username:password@]tcp(host[:3306])/database-name?timeout=10s" where Amass will connect to a MySQL database | -### The bruteforce Section +### The `bruteforce` Section | Option | Description | |--------|-------------| @@ -284,12 +289,11 @@ Note that these locations are based on the [output directory](#the-output-direct | minimum_for_recursive | Number of discoveries made in a subdomain before performing recursive brute forcing | | wordlist_file | Path to a custom wordlist file to be used during the brute forcing | -### The alterations Section +### The `alterations` Section | Option | Description | |--------|-------------| | enabled | When set to true, permuting resolved DNS names is performed during the enumeration | -| minimum_for_word_flip | Number of times a word must be seen before using it for future word flips and word additions | | edit_distance | Number of times an edit operation will be performed on a name sample during fuzzy label searching | | flip_words | When set to true, causes words in DNS names to be exchanged for others in the alteration word list | | flip_numbers | When set to true, causes numbers in DNS names to be exchanged for other numbers | @@ -297,11 +301,19 @@ Note that these locations are based on the [output directory](#the-output-direct | add_numbers | When set to true, causes numbers to be added and removed from resolved DNS names | | wordlist_file | Path to a custom wordlist file that provides additional words to the alteration word list | -### Data Source Sections +### The `data_sources` Section -Each Amass data source service can have a dedicated configuration file section. The section is named just as in the output from the 'amass enum -list' command. +| Option | Description | +|--------|-------------| +| ttl | The number of minutes that the responses of **all** data sources for the target are cached | + +#### The `data_sources.SOURCENAME` Section + +| Option | Description | +|--------|-------------| +| ttl | The number of minutes that the response of the data source for the target is cached | -This is how data sources can be configured that have authentication requirements. +##### The `data_sources.SOURCENAME.CREDENTIALSETID` Section | Option | Description | |--------|-------------| @@ -310,6 +322,12 @@ This is how data sources can be configured that have authentication requirements | username | User for the data source account | | password | Valid password for the user identified by the 'username' option | +#### The `data_sources.disabled` Section + +| Option | Description | +|--------|-------------| +| data_source | One of the Amass data sources that is **not** to be used during the enumeration | + ## The Graph Database All Amass enumeration findings are stored in a graph database. This database is either located in a single file within the output directory or connected to remotely using settings provided by the configuration file.