TL;DR: Reporting sucks, rarely does anyone enjoy it. Serpico is a tool that helps with reporting and makes it suck less through collaboration and automation, saving you time that you’d rather spend pentesting. Serpico is easy to install and works out of the box, yet highly customizable. Automating AND customizing your reports has never been more painless (I’ve tried lots of solutions). It might make you enjoy reporting…maybe 😉

https://www.github.com/serpicoproject

A case study in pentest reporting using Serpico

I first learned of Serpico through a good friend (and project developer) Pete Arzamendi (bokojan). It was developed by pentesters faced with the same reporting challenges I often battled. Will Vandevanter (@_will_is) used his wickedly awesome knowledge on Office XML to develop Serpico, a powerful pentest reporting tool. He’s also the reason why I’m obsessed with Ruby and Sinatra.

So you might be wondering, haven’t I heard of Dradis or MagicTree? Yes, I’ve heard of them, and during every new release I’d install them and hope for it to ease our reporting pain, but they always feel short.

Our existing solution was a report template in Word with custom document properties as variables. We’d have another Word document containing all the findings that we’d crib from. Unfortunately, the existing reporting solutions increased our time because we were always having to heavily modify them or spend time dealing with software and report generation errors.

Existing challenges related to report automation:

• Overly complex applications – I don’t want to spend hours managing a complex solution. More time should be spent on crafting a quality report, not managing the automation tool.
• Time consuming to customize – Our team has a few unique ways of doing things and customization should be easy.
• Reliability – Solutions never worked out of the box, and if you managed to get it working, it never remained working for long, or a user could easily break it.
• Portability – Wouldn’t it be nice to have your reporting solution be centralized but flexible to run locally if needed?
• Team collaboration – Multiple pentesters should be able to contribute to the report without stepping on each other’s toes.
• Reports always needed a lot of tweaking after being generated – I don’t want to run macros if I can avoid it, or substitute document properties. This should all be handled by the reporting tool.
• Simplicity in design – Other tools try to manage my data, do too much automation, or just don’t have fully working basic features (generating an error free Word document).
• Managing templated findings – Over time you tweak your findings, find better ways to word them, add new resources, or create a new finding during an engagement. Adding these changes back to the master

Features of Serpico and how we benefit from them

Serpico was quick and easy to install. I went from install to a customized generated report within 30 minutes. Update: Recently an omnibus packaged installer was developed, making the install even faster! I added a finding to a test report and out popped a word docx with no errors, no funky formatting issues, exactly like I always wanted. Will has done some research with Office XML, giving him a good understanding of all the Microsoft nuances that make this task more difficult than you’d think.

Here is a brief list of features that I find useful as a penetration tester:

• Templated findings – You create template findings and can reuse it in any report. When you add the finding to a report, it’s easy to customize that finding to tailor it the client. If you like the changes you made to the finding you even have the option to upload it back to the templates database with a push of a button. This drastically reduces repeated writing.
• Custom meta language allows for programmatic generation of reports – For loops and if statements supported. This is helpful in generating tables of data and layouts by severity, category, etc.
• Variables –Serpico also has the ability to create user defined variables so you’ll never be limited. These are managed from Serpico.
• Written in ruby using Sinatra and Haml – This makes the project easy and fast to customize. Example: We wanted a dual approval approach to newly created findings. We added an additional field called “reviewed”. When a finding was peer reviewed for technicality by another pentester it would get marked as reviewed. When it was reviewed for grammar by our technical writer it was then marked as “approved” and the finding template would be available for everyone to use.
• Screenshots - Upload your image, use the meta language to embed in your finding and that’s it!
• Automatic vulnerability mapping – If you have a vulnerability that can be detected via a vulnerability scanner, Serpico can automatically add your custom written finding associated with the vulnerability from popular scanning tools. It does this by CVE, Nessus ID, Burp ID, etc.
• Metasploit Integration – You can view hosts and vulnerabilities from any format that Metasploit supports. This feature is new and evolving.
• Easy collaboration – There is an approval option to each finding, you can manage users and their access to reports, you can view historical edits of findings (like a wiki), and support for multiple report templates for different project types.
• API and scripting – Serpico can be very powerful. There’s examples on how you can import vulnerabilities from VulnDB via scripting.

Centralized vs Distributed

Serpico supports both. Currently we use a centralized model. All users connect to one instance of Serpico to do reporting. However, on a couple occasions we were forced do an onsite pentest with no Internet access and without any sensitive data leaving the premise. One of us simply installed Serpico locally and using its import and export features, we were able to move all of our templated findings to our local instance very quickly.

Tips if you choose to use Serpico

• Start by customizing the provided template.
• When creating a customized report template, make one change at a time. If you make a mistake and foobar your template, it will be easier to find your error.
• Stick to the approval process, straying away from that might mean you’ll have a bunch of newly (poorly written) templated findings that were hastily created by users.
• DO NOT USE SERPICO TO AUTO GENERATE VULNERABILITY SCAN REPORTS. Serpico is all about quality reporting. Blindly converting a Nessus report finding by finding using this tool means you are contributing to low quality reports that we see in this industry. Tailor each report to your client’s needs.
• Variables are not supported in headers and footers, remember that.
• Provide developers with feedback to continue making it awesome.
• Enjoy spending less time reporting!

I wrote this on the plane to Blackhat and Defcon 2016. The Serpico team asked me to to join them at Blackhat Arsenal and I’m happy to help! Stop by to see a working demo and say hi. Follow @SerpicoProject for future updates.

@caseycammilleri