Eyewitness

May 13, 2014Christopher Truncer Development, Featured Category EyeWitness, EyeWitness guide, EyeWitness usage guide

NOTE: This post is now out of date – check this for the latest info – https://www.christophertruncer.com/eyewitness-2-0-release-and-user-guide/

I originally released EyeWitness in February in what I thought was pretty functional state.  When released, EyeWitness came in at about 400 lines of code.  Since February, it has had multiple new features added to it (which I will go over in this post), and its code base has expanded to about 1600 lines of code. I’d like this post to act as a usage guide of all normal usage scenarios that I can think of.

I’ll start off by describing how I normally use EyeWitness.  I typically call EyeWitness, provide it a text file (with each URL on a new line), and let it run.  If I have a .nessus file or nmap.xml output, and it has more than 350 URLs, I’ll run EyeWitness with the –createtargets flag (explained below), and output all the targets to a single text file.  I typically then split that file up into roughly 300 URLs per text file, and then either script up EyeWitness to run one after another, or run scans simultaneously.  However, different situations might cause EyeWitness to need to be used in a different manner, so hopefully this EyeWitness usage guide can help explain all of its features.

Python:

The bare bones, and likely most common, use of EyeWitness is to provide a single URL, or multiple URLs within a file for EyeWitness to screenshot and generate a report.  To provide a single URL, just use the –single flag as follows:

EyeWitness also accepts files for providing the URLs.  The file can be provided in the following formats:

• Single text file with a URL on each line
• Nmap XML output
• .Nessus file
• amap file output

To perform a scan, using any of these filetypes, just provide the -f flag as follows:

By default, EyeWitness will attempt to screenshot the website, and have a max timeout of 7 seconds.  If it takes longer than 7 seconds to render the website, EyeWitness will skip to the next URL.  If you wish to change the timeout of EyeWitness, use the -t flag and set it to the max number of seconds you want it to wait to render a website.

Once EyeWitness has finished navigating to all URLs, and has generated a report, EyeWitness outputs the report to the same directory EyeWitness is in, and names it based off of the date and time the scan ran.  If you want to change the directory name that EyeWitness outputs its report to, use the -d flag and provide the name.  When using the -d flag, you can provide just a name, and EyeWitness will create the report using the provided name within the same directory as EyeWitness.  You can also provide the full path to a directory, and EyeWitness will create the report folder at that location (just make sure you have the proper write permissions).

Sorted reporting was a feature brought up to me by Jason Frank (@jasonjfrank) as something that would be helpful when reviewing the EyeWitness report.  If we had a way to make EyeWitness analyze the different web applications, and group similar web apps together, then it would be easy to quickly sort through/review the groups you want to target.  We envisioned similar printers, mirrored web pages, etc. all grouped together within the report.  Lucky for us, Rohan Vazarkar (@cptjesus) worked on adding this feature in.  His pull request was merged in on April 22nd, and EyeWitness will now attempt to sort all results based off of their title within each report generated.

The –localscan option was added based on a request from David McGuire (@davidpmcguire).  We wanted a way to perform some basic port scanning for web servers once a machine has been compromised. Currently, one way to do it is to drop Nmap on the compromised machine, but if we did that, we’d have to install winpcap on the machine, which requires admin rights.  Instead of this, you can drop the windows Eyewitness binary, and provide the –localscan option with a CIDR range to scan.  EyeWitness will then try to find any ip listening on 80, 443, 8080, and 8443 within the provided range.  All live hosts listening on any of those ports will be added to a file that can be fed back into EyeWitness.

The –createtargets option came about when I wanted to have EyeWitness just provide me a list of all web servers from the XML output of Nmap or Nessus.  All web servers that EyeWitness finds within Nmap’s xml output, or the nessus file will be added to a file containing the target servers.  Just provide the filename you want the your targets file to be called.

The user agent definition and cycling came about from working with Micah Hoffman (@webbreacher), Robin Wood (@digininja), and Chris John Riley (@ChrisJohnRiley).  After a lot of discussion on how best to carry out user agent switching and comparison, the feature was added in.  First, you can simply provide the –useragent option, and it will use any string you provide as the user agent.

You can also use the –cycle option along with either browser, mobile, crawler, scanner, misc, or all.  When using this option, EyeWitness makes a baseline request.  It will then make subsequent requests with user agents of the “type” you specified.  If the subsequent requests deviate “too much” from the baseline request, the subsequent request will be added in to the report letting you know it was different from the baseline.  The deviation is currently based on the length of the source code the web server provides to EyeWitness.  By default, the deviation that’s used to measure if the requests are different is set to 50.  To change this value, use the –difference flag and provide the new value to use.

Finally, the –jitter option was one that was discussed about at a NovaHackers meeting, and also requested by @ruddawg26.  To use this option, provide all the scan parameters you would normally provide, but add on the –jitter parameter at the end, and provide the base number of seconds that it deviates from.  Now, EyeWitness will randomize the order of the URLs provided (via text or XML), and will also have a random delay between each request.

Finally, EyeWitness has a –open flag.  If you provide the –open flag, each URL passed into EyeWitness will also be opened up in a web browser.  Your command string might look similar to the following:

Ruby:

To generate a report for a single website, you need to use the -s or –single flag and provide the URL.

For file based input, you will need to specify the filetype that you are providing.  If giving just a normal text file with each URL on a new line, use the -f or –filename switch.  If using providing Nmap XML output, you’ll need to use the –nmap flag, and .nessus based input requires the –nessus flag.

The –skip-sort flag is used to tell EyeWitness to not auto-group similar web pages together in the report.  This can be helpful if you want to see report pages as they are available, instead of waiting until the very end.  However, if this flag is used, similar pages will not be grouped together.

The –no-dns flag is used when you want EyeWitness to find web servers via their IP address, not their DNS name, while parsing Nmap XML output.

This pretty much covers the features of EyeWitness.  If anyone has any questions, don’t hesitate to get in touch with me.  Also, please be sure to send any signatures you might have made!