Twigs can discover hosts in two ways as below:
- Discover the current host where is twigs is installed – local host discovery.
- Discover multiple hosts remotely – remote host discovery.
During host discovery, you can perform SSH audit and Host benchmarks as well.
Local host discovery
Host discovery (local) is a fairly straightforward process. It needs twigs to be installed on the required host. This is where twigs can act as a lightweight agent and discover details about packages, patches, services and other configuration on the host. Additionally twigs can also run host benchmark checks for security posture assessment.
Pre-requisites
Twigs should be installed on the required host. It can be scheduled to run on a regular basis (daily, weekly) using cron or similar service.
Steps involved
Once you have twigs installed on the required host, then you can follow the steps below for discovery local host as an asset in ThreatWorx:
- Open a new shell / terminal
- Check that twigs is installed and running properly by running below command:
twigs host -h
- You can run the command as below:
twigs host [--assetid ASSETID] [--assetname ASSETNAME] [--no_ssh_audit] [--no_host_benchmark] [--check_vuln CHECK_VULN] [--check_all_vulns]
- After discovery is complete, you can login into ThreatWorx Console to view the newly discovery asset.
Examples
$ twigs host --check_all_vulns
Discover this host as an asset in ThreatWorx
$ twigs host --check_all_vulns --no_ssh_audit
Discover this host as an asset in ThreatWorx but skip SSH audit
Remote hosts discovery
Twigs can help discover multiple hosts easily using remote hosts discovery.
Pre-requisites
Twigs remote discovery for hosts uses a CSV (comma-separate values) file which provides details about the hosts to be discovered. The CSV format has support for specifying individual remote hosts via hostname or IP address and you can specify a CIDR (Classless Inter-Domain Routing) or subnet range to discover hosts in your GCP cloud.
Host CSV file
The format of the remote hosts CSV file is as follows: hostname,userlogin,userpwd,privatekey,assetid,assetname
The first line in the CSV file is the column header record and it has the columns as mentioned above. The subsequent lines in the CSV file are data records.
Here are details about the respective columns in the remote hosts CSV file:
- hostname – This column is mandatory and can contain hostname or IP address or CIDR range. The CIDR range option allows organizations to easily discover multiple hosts in the same subnet.
- userlogin – This specifies an user on the specified host. It is mandatory.
- userpwd – If the user requires password-based login on the specific host, then specify the password in this field. If you have specified a encrypted private key file, then specify the “pass phrase” for private key file in this field. Note it is recommended to secure the information in this field using the ‘–secure’ option.
- privatekey – If the user requires private key based login on the specific host, then specify full path to the private key file.
- assetname – Specify the “Asset Name” for the host.
Here is a sample remote hosts CSV file:
$ cat remote-hosts.csv
hostname,userlogin,userpwd,privatekey,assetname
michigan,john,johnpwd,,michigan
192.168.2.1,patrick,patpwd
54.133.4.23,ec2-user,,/root/inventory-key-pair.pem
128.45.67.64/30,sysacc,,/home/sysacc/private-key.pem
Let us better understand the sample remote hosts CSV file:
- The first line is the column header. It is recommended to simply copy-paste it “as is” in your CSV file.
- The second line is used to discover a host named ‘michigan’. It depicts how one can specify the assetid and assetname values.
- The third line specifies the host using its IP address along with user / password combination for login.
- The fourth line specifies a private key file for login.
- The fifth line specifies a CIDR rage along with user and private key.
Since this file allows host credentials (user name, password) to be specified in plain text, twigs also allows to encrypt the password column using the ‘–secure’ option
This option which asks for a password (interactively or on command line) and encrypts the credentials portion of the CSV file. For e.g.
twigs host --host_list remote-hosts.csv --secure
If the CSV already has a records with encrypted credentials, these will be skipped. Also twigs will ensure that the same password is used to encrypt the CSV if it was ever encrypted before. Also the password can be specified on the command line if required using the ‘–password’ option. The CSV file can have a combination of encrypted and non-encrypted data as new records with credentials can be added to the CSV after it has been encrypted.
Host discovery mode in twigs provides organizations with powerful way to discover multiple hosts in a simple and uniform manner.
It is recommended that you secure the credentials shared in the CSV file using the ‘—secure’ option provided by twigs.
Steps involved
You can follow the steps below for remote hosts discovery:
- Open a new shell / terminal
- You need the following information to run twigs command:
- remote_hosts.csv file created earlier as mentioned in pre-requisites section
- Run the twigs command as below:
twigs host --remote_hosts_csv <<PATH_TO_REMOTE_HOSTS_CSV>> [--password PASSWORD] [--no_ssh_audit] [--no_host_benchmark] [--check_vuln CHECK_VULN] [--check_all_vulns]
- The discovery process may take some time depending on the number of hosts to be discovered.
- After discovery is complete, you can login into ThreatWorx Console to view the newly discovered assets.
Examples
$ twigs host --remote_hosts_csv ~/my_cidrs.csv --check_all_vulns
Discover all hosts enumerated in “my_cidrs.csv” as assets in ThreatWorx.
$ twigs host --remote_hosts_csv ~/my_cidrs.csv --check_all_vulns --no_host_benchmark
Discover all hosts enumerated in “my_cidrs.csv” as assets in ThreatWorx, but do not run host benchmark checks for these.