Audience Identification: Penetration testing reports may be only for the internal audit team and/or the IT department (i.e., a technical audience), or for the management executives and the technical team. The report must always be drafted with the target audience in mind. For the technical audience, the writer can conveniently use jargon and skip detailed explanations of attack types. Some points to keep in mind for a technical audience:
1. The reader wants a quick glance at the vulnerability ratings as well as corresponding details with accurate referencing. So keep the report succinct and try to retain all data relevant to a particular finding in one location, preferably on the same page.
2. When you present the first finding, the reader expects a similar pattern for the remaining findings. So, follow a uniform pattern of vulnerability specifications. For example,
a. Risk Description
b. Risk Level
c. Affected IPs or URIs
d. Potential Damage / Corporate Loss
e. Recommendation / Remediation
For a non-technical audience – Executive management, IT Manager or Risk Manager, the jargon should be minimalistic and the vulnerabilities should be described from the user’s perspective such that it is simple to comprehend the vulnerability. For example, ‘a parameter manipulation on the order confirmation page of a shopping cart application’ may be re-worded to ‘Price Manipulation in XYZ shopping cart’. The idea is to familiarize the vulnerability. The managerial perspective looms at the macro-level. So they are concerned with the overall risk the sum total and individual vulnerabilities pose to the organization and how soon these vulnerabilities can patched. Thus one-glance reporting plays a key role here. Constructive use of pie-charts, 3-D bar graphs or simple tables with a good color-coding scheme may prove useful.
Structure Determination: Barring the common elements of a report (Executive Summary, Conclusions and Appendix), a typical penetration testing report at NII Consulting consists of two main components as part of the technical section. These are: Network-related Vulnerabilities and Web Application Vulnerabilities. As you may have noticed, the Network-related Vulnerabilities show the port scan status and service banner disclosures and the Web Application Vulnerabilities section provides tabular listing of the findings in the order or threat rating or risk level. The technical section can also be structured as per the approach of the penetration testing.
Classification of Findings: Another important aspect which determines the overall impact of the report is how you classify the findings. This decision overlaps with that of structure determination. Findings can be presented in the order of threat rating or can be classified under different attack categories. Cross-site scripting, SQL Injection, Parameter Manipulation – all can be classified under Insufficient Input Checks. Other such categorizations can sometimes help the client assign responsibilities for resolving issues to different teams.
Recommendations: Some important points to consider while writing recommendations:
1. Provide appropriate URL references if an upgrade or patch is recommended
2. Give the details – if an upgrade is needed mention the version to be upgraded to, if an XSS vulnerability exists don’t just write ‘data needs to be filtered’. Specify what kind of characters can be replaced.
3. You may also mention URLs for further reading on the vulnerability and other related vulnerabilities
These are only a couple of pointers needed to write a good report. A lot more goes into writing a penetration testing report that adds value.
On a light note:
Jane Watson, in her article, The Recipe for Good Reports, says

Some people write the same way as I learned to cook spaghetti.
When I was at university, I was taught a surefire way of cooking “perfect” spaghetti: Add noodles to a large pot of rapidly boiling water. When you think the pasta is about ready, use a fork to remove a strand from the pot. Flick the strand at the wall. If the noodle falls behind the stove, the spaghetti is not fully cooked. If it sticks to the wall, get ready to serve.
This is the same method some people use to write a report. They have a vast number of facts boiling in their minds, and they believe if they throw out enough of them, some will eventually stick in the reader’s mind.

• Name
• Date of Discovery
• Vulnerability Type
• Impact
• Exploit Code / Proof of Concept
• Vulnerability Description
• Software Affected
• Platforms Affected
• Solution
• Workaround
• Vendor Links - Advisory, Patches, Upgrades

To determine the order of importance, the best option is to slip into the shoes of the reader. A simple and quick approach is to look at a vulnerability in systems as if it were an impending blemish to or malfunction in, your most loved Pontiac, Lamborgini, Jaguar, Ford, Audi….you get the flow. So to begin with, you definitely want to know what the fault is about. Next come the fault vectors, followed by when it was discovered by your tribe. Next in line, you want to know how to find out if your baby is prone to any malfunction, and if she is, how would you find out ? You obviously do not want to rely on hearsay, so you’d prefer to see some evidence of malfunction with another car. Once you are convinced, you may want to find out how long will she be out of service (i.e., the total impact or repercussions). Finally, after dreading the impending malfunction, you would want to know in advance how to fix it or avoid it altogether and which is the nearest dealer or service center that can be contacted!

Now, as security analysts, advisors, and consultants, lets try to list questions on vulnerabilities in order of usable importance in-line with the automobile malfunction.

1. What is the vulnerability about ?

2. How can it be exploited ?

• Remotely/Locally
• Procedure

3. Which software and platforms are affected ?

4. Is the exploit code available ? Where can I find it ?

5. How do I know if I am affected ?

6. When was it reported and has it been updated ?

7. What is the direct and indirect impact ?

8. If I am affected, how do I patch or upgrade the affected component ?

9. If for some reason, I cannot apply a patch or upgrade, is there a workaround available ?

A lot of web sites like SecurityFocus, Secunia, FrSIRT, US-CERT, X-Force, etc. provide excellent vulnerability details. Some provide logical sections of the vulnerabilities on different tabs, whereas some provide detailed descriptions and references on the same page. Both these methods are useful for different sets of users. However, this scribe was only to bring forth the importance of order in the context of usability.

Please feel free to give your inputs.

Note: The criticality level has been left out intentionally because it is one component which differs greatly from one web site to another and also, a scratch on your beloved car would remain a scratch, no matter how big or small it is!

Technorati: Security Advisory Structure, Advisory Order of Importance, Writing Security Advisories

Microsoft Office 2007 Beta has come up with some easier methods to maneuver the security options in its all new swanky interface. It has done away with installing add-ins for purging the documents off any personal information. It now comes with an in-built document inspection utility. Moreover, connecting to shared workspaces has become easier and the ‘Finish’ sub-menu under the Office main menu has almost all of the security options bundled together at one location.

So lets scan through the different security options via Word 2007’s interface in the following screenshots:

1. Properties’ Information can be manually edited before storing or emailing documents

2. Inspect the document for:

• Comments, Revisions, Versions and Annotations
• Document Properties and Personal Information
• Custom XML Data
• Headers, Footers and Watermarks
• Hidden Text

The ‘Inspect’ option will check for the existence of the checked items and will ask the user if he/she wishes to delete the information, if found. This is a better alternative to the ‘rhd.exe‘ add-in available from Microsoft to remove hidden data.


3. Restrict Permissions for accessing the document

This sub-menu provides three quick options (just like Word 2003) of providing unrestricted access (selected by default) to all users, restrcting access to a set of users (with the help of valid passport IDs) and the last option which also allows changing the ID of the user restricting access.

4. With the introduction of XPS format, and the use of prior versions of MS Office, the developers could not have done away with this feature. Instead of surprising the receiver with an incompatible document, now you can check it yourself.
If the document has elements not compatible with previous versions, the compatibility checker will give a prompt similar to the one below:

5. The last option on the ‘Finish’ sub-menu allows quick finalization of the document. You can mark it ‘Read Only’ before distributing it.

6. The next few security options which are not used as often are clubbed in the ‘Trust Center’ option.
MS Office Main Menu > Word Options > Trust Center. On clicking ‘Trust Center Setting’, you get a range of security settings that can be changed. Trusted publishers, locations, Add-ins, ActiveX Controls, Macro Settings and the Privacy Settings. The Privacy Options used to be on the ‘Security’ tab under the ‘Options’ sub-menu in the previous versions.

If you know of any hidden security features, do leave a comment.

Tonight it’s time
Choose a direction
If you fail
You can make a correction
Slower now
Make life faster
Make your mind
Up for once this time
- ‘Tonight’, Divine Discontent, Six Pence None The Richer

Like any other vocation, technical communication has its own set of diverse decisions to be taken at different stages while you are at it. One such decision is that of sticking to a single domain. Seldom do you find people who know what their true calling is with respect to their profession, leave alone the specialization. And what does it take to know your true calling - time, experience, knowledge, instinct, maturity, self-awareness? Well, it could be any or a combination of any or all of these. Technical Communication in itself is a long learning trip. What and how you decide to learn is your choice. A choice which,

• you know you will not regret
• blurs the line between work and leisure
• keeps you asking for more
• wins you respect and confidence
• helps you focus
• gives you a sense of belonging, and much more.

In my discussions with several successful technical communicators on what keeps them going, I have observed a common denominator - their learning experience and challenges while working in different domains. To an extent the words sounded as clichéd as the replies from film and television personalities saying, “We love to be in the profession because we get to play a variegated set of characters which we otherwise cannot”. However, it is true; worthwhile having several exhilarating experiences in one lifetime!

Subash Babu and Vijayalakshmi Dandu, in their article ‘Domain-Specific Technical Writing’ point out three different angles for observing the difference between domain-specific writing and everyday writing. I quote (condensed),

1. Use or usage scenarios are different for domain-specific products, and so the audience analysis may differ.
2. The process of writing is distinct. A “click-here-click-there” approach may not usually work when writing documentation for specialized domains.
3. General software applications are easy to use, and technical writers can use them to understand the user’s role better. This may not be the case with domain-specific products.

I concur with all three and would point another angle - Nature of documents developed may differ depending on the domain and thus the writing approach. For example, no domain will have unique document structures like ‘Case Reports’ as in Medical Writing or Security Advisories as in Information Security.

A general set of advantages of delving in different domains look like:

1. Increased exposure
2. Diverse challenges
3. More opportunities
4. Freedom from monotony

When shifting domains, many times, technical communicators are required to learn new tools and technologies which may not be possible to achieve while retaining your primary focus on a single domain. Moreover, its like tech-writer-schooling (if I may coin the term) all over again, which for a lot of people is a fad. You start learning from scratch, kick-start with the fundamentals along with getting the client requirements, carry out an audience analysis based on the domain, type of document, organization writing style, and region-specific issues. Next comes preparing a plan for document development, again keeping the above parameters in mind. The consequent phases of the Document Development Life Cycle (DDLC) may not be different from a usual scenario except for the maintenance phase where the frequency and type of maintenance will differ largely from one domain to the other .

A lot of technical communicators shift domains for otherwise obvious reasons like a pay-hike, change in environment, better designation, and increased responsibility. However, very few lucky ones find their true calling in the process. So is it possible to find it on the other side of the fence? Lets see.

This side of the fence is full of people who have fallen in love with the domain, or accidentally remained stuck to it, or could not find other exciting opportunities. I’d choose to focus on the first category as we are talking of choices and finding your true calling. Domain-specific writing has its own set of advantages:

1. Reducing dependence. Prolonged exposure to the same domain, considerably depreciates your dependence on subject matter experts (SMEs). Needless to say, if the project is not product-specific, document development becomes a breeze.
2. Knowing the nitty-gritty gives you ability for proposing creative approaches for presentation of concepts while keeping usability intact.
3. Narrowing your focus to one domain, gives you time and space to explore all the available resources, question, break-apart and challenge techniques for better understanding.
4. Building your own space. Gives you an opportunity to create a niche for yourself and create a personal brand.
5. Last but not the least, some people still believe in being ‘Master of ONE trade’

If the domain is challenging enough to hold your interest for more than two decades (my appropriation), and teach the tricks of the trade, nuances of the technology and gives you the power to innovate while you develop documents, its a choice well-made! Again, domain-specific writing does not imply specialization in only one domain. A technical communicator may be considered a domain-specific writer in one more domains if

• He/She has executed quality projects showing (irrespective of a stringent numeric parameter with respect to time or number of projects)
  • Domain Expertise
  • Ease of Use
  • Efficient Document Planning
  • Quick and appropriate problem-solving

  And other common characteristics: if

• Each project has been a learning experience
• He/She has been able to add value to the deliverables
• He/She learnt something new with each project and attempted to improvise the next accordingly.

Its all about choices, right from the time you were in school, and had to pick second and third language subjects, to college days where you had to decide which subject to major in. How many people find their choices worthwhile? How many people suffer mid-career crisis?

The points mentioned in this article are certainly not exhaustive. These are simply blurbs. I leave it your imagination to expand on these. Ricardo Semler, in his book ‘The Seven Day Weekend’ talks about giving his employees an opportunity to soar. They can soar when find their true calling. I wonder how many of us as employees or otherwise have found our true calling? Have you found yours? If not, how far are you from YOUR CALLING?

Domain-Specific Writing - both the views

‘Several Domains’ Camp: A majority of writers love to write across domains. A classic example of one such writer is Janani Gopalkrishnan. Some of her work can be found here. Writers in this camp often find themselves researching constantly for newer concepts, methodologies and principles. The experience of learning from scratch seldom fails to give a high. Besides, writing across domains is always on the top of the list of reasons for seeking newer challenges with each project.

‘Single Domain’ Camp: Writers in this camp have more or less made a niche for themselves in their respective domains. Such writers eliminate the need of subject matter experts to a great extent and are seasoned to manage documents such that delivery time reduces considerably. Not only do they exhibit confidence in managing the project more effectively but also end up providing value additions to the deliverable with ease.

iScribe’s Objective

The objective of this blog is to spread awareness about this highly specialized field of Information Security Documentation and guide technical experts to create crisp, useful documentation. The blog also aims to motivate technical writers in other domains to follow suit and write more about their chosen domain.

iScribe’s Audience

Like any other domain, Information Security has its standard set of documents like the proposals, reports, guides, online help files and white papers. Then why this blog? The second reason for starting this blog is to benefit people in the domain - security analysts, information security officers, security advisors, etc. to be able to manage their documentation more effectively and address the unique documentation requirements of audits, penetration tests, compliance exercises, digital forensics investigations, etc. The blog is also for technical writers working for information security companies or who are interested in Information Security.

iScribe’s Showcase

The blog will attempt to cover a range of topics from how to write vulnerability assessment reports to discussing security options of popular publishing software. A brief list of topics you will read on soon, are:

• Writing Vulnerability Assessment Reports
• Writing for Executive Managment
• Converting your reports to Powerpoints
• Security Advisories and XML
• XML Security
• Security Tips for Using MS Office

and much more. iScribe will constantly post on effective technical communication in Information Security. Keep watching this space for more on InfoSec Documentation.