15 solid tips on producing good documentation

Documentation has been very dear for me for a long time. The usefulness and importance of documenting is just so immerse! In this post I’ll take a chop on some of my thoughts on documenting.

  1. Keep it simple stupid. Documentation should be brief and to the point. Do your best in having economy of words, don’t spend them easily. Simple bulletpoints goes a far way! Use simple langugage and short sentences.
  2. Use English when writing! Even if you are an entirely non-English shop, write in English still. You never know when you are going to expand into neighbouring countries that may require you to share information in English. Also, I am sure you’ve had to work with a consultant one-time or another, where the consultant is only English speaking. And no, Google Translate won’t cut it.
  3. Screenshots or video are not a preferred way to document. They can compliment existing documentation, but should not be your only documentation.
  4. Don’t create documentation using only copy/paste from whitepapers or the like. Only do this if it is a 100% fit for purpose. Instead consider linking and referencing the material rather than copy it.
  5. Capture the essence of the information you are creating. Make it as simple as possible to read and understand the documentation. “Economy of Words” gets you a long way!
  6. Don’t include passwords in the documentation. Sensitive information is usually OK as the documentation should be behind access restrictions, however passwords are not. Passwords should be changed regulary, so instead of storing them in e.g. the wiki, store them in a password manager. I’ve written a blog about using password managers here.
  7. Documentation should be a part of business requirements. Don’t let systems, services or other things go live without having at least a simple documentation readily available. It shouldn’t take long to set up some simple documentation scaffolding and adding some information to it.
  8. Keep the documentation platform highly available, good performance and ease of use. A wiki, i.e. Mediawiki, is excellent for this. If you make documentation tedious and hard, it won’t be used. Trust me on this!
  9. Knowledge is power; hence many will avoid documenting to keep them valuable to the business. Don’t be this guy! First of all, you will quickly be noticed using this strategy, second, any thriving business will be looking to keep good employees. Documenting, and thus helping build a healthy organisation, will ensure you are sticking around for the end game.
  10. Don’t get stuck doing the same repeatable tasks over and over again. Create good procedures and next time, someone else might be doing your tasks. Spreading the knowledge will allow you to move on to more challenging tasks. Having solid documents may even allow you to easily out-source your work load to the servicedesk.
  11. Keep your documentation solution always ready. If it’s a notepad or a wiki, always have it signed in and ready for you to type in. The moment it is not trivial to document, you are most likely going to skip it. Make it as easy as possible for yourself to create notes.
  12. Do not wait until the last minute to write documentation. You will forget what you did! Instead, write it as you work. If you did something wrong with your setup, requiring you to redo parts of the documentation, that is fine. Just go back and edit the step which you had to change.
  13. Update the documentation, don’t let it go stale. Stale documentation is bad, and wrong documentation is even worse. Ensure that it is simple and easy to update documents.
  14. Not everyone is an author. However, you still need to write something. Just remember to keep your information easily readable and understandable. Point back to point 1, KISS.
  15. Avoid repetition. Duplicate information is a no-go. It is a hassle to update information multiple places, instead use your documention platforms features for inclusion of duplicate information from one master source.

Got some tips of your own? Leave it in the comments. Thanks for reading!

How to Password Reset

A lot of companies and organisations does not do password resets properly today. Here is a recipe on how to do it securely.

  1. User enters the login page. This must be loaded over HTTPS.
  2. User clicks the “Forgot password” button. The user must then supply something unique to the user, e.g. email or username.
  3. The backend system affirms the details submitted, but does not give away if the details are correct or not. The system simply states that “A password reset email has been sent to the user, if it exists”.
  4. The system sends an email to the email address behind the username . The email must contain the following:
    • Who ordered the email? IP address and the country behind that IP is useful information.
    • Time and date the reset was ordered.
    • Some information regarding the password reset function and a notification to ignore this email, if it was not them who ordered it.
    • A unique link back to the system where the password reset in itself is done. The link needs to have the following properties:
      • It should contain a high entropy unique key, e.g. a long and strong unique key. This key should be as good as impossible to guess.
      • A fixed time the key is valid, e.g. the link only allows password resret if it is clicked within 15-30 minutes.
      • The link must be loaded over HTTPS.
    • Inform on the duration the link is active and that it is a one-time use link.
  5. The user is then taken to a form where he can enter his new password.
  6. Send a new email to the user, notifying that his password was in fact changed.

LinkedIn Phish – Investment Proposal

Today I received the following message from a LinkedIn contact:


I hope all is well with you, please review this recommendation for an investment opportunity which am considering a partnership with you if you’re interested. I hope that the reasons for this investment, which are alluded to in more details in the enclosed document( http://parkingticketing.co.uk/libraries/investment/dbnew ), will make you consider this alliance positively.

I hope you you will reply soon. With best wishes,

Warm Regards,


I think this looked wierd, so I opened the site in a safe browser and explored a little. It turned out it was definitely a phish. The landing page looks thrustworthy:



The bad guys left a mistake though at http://parkingticketing.co.uk/libraries/investment/dbnew.zip . This zip file contains some simple scripts that sends all credentials submitted to the following email address: willysnows1952@gmail.com .The script then redirects you to this PDF: http://www.morganstanley.com/about/press/ip-poll-national-432013.pdf

I’ve sent an email to ParkingTicketing.co.uk to notify them about this phish.

SQL Join types explained with 1 picture

Venn diagrams are often over-used, however in this scenario it is a truly perfect fit for explaining SQL Joins.

If you ever wonder how a join works or which join you should use, take a look at this picture:

SQL Joins


[important]Credits to CL Moffatt for creating this picture: http://www.codeproject.com/Articles/33052/Visual-Representation-of-SQL-Joins[/important]

Password managers, why isn’t everyone using them already?

I am very surprised that people, still today, do not have sufficient knowledge of the existence of password managers. They make IT life so much easier for us!

Think about what us security people are preaching: “You need to have a unique password for every single account”. That’s pretty rough demand, especially if the password is supposed to be truly unique, not just a spin-off of a master password. Having this in mind, here is a statement I find it hard to dispute:

[important]It is impossible to remember all your different usernames and password combinations. Additionally it is impossible to create passwords that adhere to all the different policies, that all the different systems have in place. [/important]

Windows Live only support 16 characters. What if your password is 20 characters, then you have to keep track of another variance of your password. Additionally, some systems limit the use of special characters, or they force you to, in some way or another, use a different password. If you are like me, you are registered on so many systems all over the internet, that you wont be able to keep track off all your passwords, let alone your usernames.

Not just passwords, usernames too

Guys, girls and foreign species; listen! I currently have 144 DIFFERENT ACCOUNTS! For these accounts I have 20-30 different usernames. Yes, 20-30 different usernames! How is ANYONE suppose to remember all that information unless you are Sheldon Cooper from Big Bang Theory? Keep in mind, you are supposed to have a unique password per service as well. This means that just a slight variation of your master password is, in theory, not good enough, as an attacker could very well crack it by learning your algorithm for varying your password. The attacker already has your password in clear-text, so he can easily read it from one of hte compromised sites you have registered at. It is not good enough to only have variance protect against automated bot attacks.

If we are going to practice what we preach, then there is no other solution than have a password manager as far as I know. Mind you, this password manager may very well be a notebook (analog paper) instead of an IT system. This to make sure your mom, grandma and others, not so techie, can also keep up with the requirements today. A notebook? Really? Really!! What are you the most worried about? A burglar stealing your password notebook, or a thief online stealing your identity?

keep calm and carry

A take on password managers

So what is a Password Managers? Well, first of all a disclaimer: I am in no way, shape or form, involved in the development, sales or companies who own Password Managers. I just find them extremely useful, hence me sharing my thoughts with you.

Password Managers store all your accounts information in a secure and good way. The only thing you have to remember is one master password in order to unlock your little database.The database lets you easy search and then copy both username and password for the account you need. It also helps you easily generate unique and secure passwords. Lending a quote from the article linked beneath:

Password managers are a simple
way to securely store all of your
different passwords for each of
your different account

So the next time you type in your password, I’ll ask you “why you bother??”, instead use a password manager. It is easier, safer and quicker!

The password manager I use is called KeePass. I use this for both personal and business use. We also use this on the IT-Operations team. I have my personal KeePass database also connected on my phone (via Dropbox), so I can easily use the logins in my manager from my phone. I have also stored my pincodes for access control cards, cell phone pins and more in this password manager. Everything I have is safely stored in an encrypted database, protected by one, strong and unique password.

Keepass can be downloaded from here: http://keepass.info/
For further reading I suggest looking at SANS Securing The Human newsletter Ouch. They wrote a newsletter specifically for Password Managers. Here it is in English:http://www.securingthehuman.org/newsletters/ouch/issues/OUCH-201310_en.pdf

You can also find it translated to other languages here:http://www.securingthehuman.org/resources/newsletters/ouch/2013

Good luck in implementing your new Password Manager. It really is easy to get started with, and there is little to no excuse not to have this today!

PS: Honorable mention to Lastpass. I have not used it myself, but many of my friends recommend it. Supposedly a very good password manager!

Security Management for 2014

futureSecurity seems to be, for many, the idea of keeping everything clinical clean, not getting hacked and preventing introducing new risk to the equations. Well guess what, there’s no such thing as clinical clean in security, and I hate to break it to you, but IT security is about minimizing loss and reducing risk. It is not about being un-hackable, because we all know that’s not possible. I dare to say, many security managers today are introducing more risk in their environment by their blatant decisions, saying NO to just about anything that may or may not introduce new risk.   

What I’ve seen in security is the quest or illusion in gaining perfect security. This involves security managers saying “No” to just about anything they can. I usually can’t settle with just a “No, you can’t do that”, because I know better. Especially when I know the proper attributes to the risk picture has not been explored or discussed yet.

This article contains my attitude and thoughts towards not accepting “No” as the only answer, and my opinion on how I think security management should be done. Whether I am right or wrong, I’ll let you be the judge of that…

Be a part of the solution, not the problem

If you catch yourself, as a security manager, saying “No” to the organization, you might notice that you are distanced out, ignored and neglected more and more. Perhaps no one is coming to consult with you anymore? To many this may be understood as an organization that doesn’t want to be secure, employees that don’t care or just people being stupid. It feels like you are swimming against the current! I’ll let you in on a small advice; it’s probably not they who are the problem, most likely it is you.

You shouldn’t make it so anyone coming to you is doing it with contempt and negativity! If you find yourself in this situation, it can soon enough become a downward spiral for your entire security team. It won’t be long until the organization look at you as part of the problem, not the solution, and they will go out of their way in order to evade you with the ultimate goal of having their problems solved, one way or another. They will do what they can to circumvent your policies, procedures and best practices, just because whenever they come to consult with the Security Team they are just faced with more problems and no solutions. They need to have their problems solved, not picked at!

Anyone approaching the Security Department should be welcomed and thanked. I’d offer them a cookie for stopping by. They didn’t have to come to you, but they did! Remember that the people approaching you are your customers. You want to make them happy, and you want them to return to you for their next inquiries. All this without forgetting your overall goal, namely protecting the business and adhering to its strategy and visions. Impossible? It shouldn’t be.

Protecting the business, while still being a “Yes Man”

Now, I’ve said you shouldn’t say “No”, but you may argue, some things are just too dangerous to put into your organization! That is why I want to prove my thinking with a use-case; a case where you are approached by users in the need of Dropbox. I won’t go into great detail in the assessment; I will however shed light on some of the important questions we need to ask ourselves. It is important to know that we can’t cherry pick the problems you want to assess, and those we don’t. There is a solution, and the users need to understand it.

So let’s pretend the organization has approached you with the request, they want to use Dropbox in order store files. A very important thing to remember is that the customers are not necessarily presenting you with the solution, but instead they have a problem they need solved and in explaining their problem, they elude to their own ways on how they would solve it. In this case they most likely need to store files and have them accessible from multiple networks and multiple devices.

Why am I calling them customers? Well, I call the companies employees for customers, even if they are my colleagues. Thinking about them as your customers is a good thing! Happy customers is returning customers; returning customers is good for business.

So with Dropbox issue at hand, it may be tempting to just say “No, you can’t have Dropbox. It’s unsafe because we won’t know where our files will be stored, and the potential for data leak is increased. We need to have appropriate control of where our files are stored, and Dropbox is no solution for that”. Now wait a minute. What do you think your users will do next? You haven’t presented them with a solution, instead you’ve only attributed to the problem. The inquiry still needs to be solved in one way or another! Your customers will most likely manage to solve their own problems, but without involving you. This is REALLY bad and probably worse if you accepted the use of Dropbox, or at least provided an alternative.dropbox

Let’s think about how we can solve the Dropbox problem, but at the same time staying aligned with security concerns of the organization. Ask yourself the following questions:

  • Have we already solved this problem? Maybe you already have a solution in-house you can use. Perhaps you already have some kind of internal storage which could be made accessible through VPN?
  • What are you trying to protect? What data are you afraid of losing through Dropbox?
  • Can data already be lost or exfiltrated through other, easier means? E.g. email attachments, USB thumb drives and the likes.
  • What are you actually worried about? Foreign states or competition spying on your data? Security vulnerabilities in the storage solution?
  • What other options do you have? Are there any other vendors in the market, providing a solution which is more aligned to your security policies?

With the above questions answered, you may be able to further conclude on whether or not Dropbox should be allowed. Perhaps you don’t want to accept the risk by using Dropbox, but the customer still needs his problems solved; what other options are there? There’s always the option to create your own private storage cloud. This could potentially be very expensive and hard to maintain, but it might be a good choice if you have the money for it. Otherwise there are many other vendors for Dropbox like functionality, I’m not talking about Skydrive or Google Drive. I am talking about professional products from vendors like EMC.

Do you see now that saying “No” to the Dropbox question isn’t as easy as you might’ve thought? There are many things to consider and right now you are loaded with a better set of data to further evaluate the way forward. Instead of saying “No, you can’t have this” you can say “Yes, you can have this, but it will cost you x amount of $ as we would require to purchase through EMC as Dropbox is not per security standard of our company”. If the customer can hustle up enough dough then why not let them have it?

The solution

antique key

The Security Department is primarily there to protect the business.  Keep in mind that you are all on the same team, even if the employees may be viewed as the organizations biggest risk. I challenge you to also think of them your biggest ally. You probably don’t see them as your enemy, but have you heard of the phrase “keep your friends close, and your enemies closer”? This applies to security. Some security people will deliberately distant themselves from the users because they consider them “stupid” and “ignorant”. This is as wrong, and we should instead approach them and befriend them.
Our mentality towards problems should be to approach them with a way to solve it. We have to force ourselves to think solutions instead of only problems. Thinking about and defining additional problems is of course good when analyzing a problem, but we have to stay on track for a solution. If your entire meeting has gone to waste just by pointing at and defining other problems, something needs to change. The focus is wrong! If this applies to you, make sure your meetings end with defined actions, a timeframe, responsible people and meeting minutes sent out to all.

Being able to be pragmatic is a really important quality which I think compliments Information Security in a brilliant way. When I look at the definition of the word, I immediately fall in love with the word:

dealing with things sensibly and realistically in a way that is based on practical rather than theoretical considerations.
“a pragmatic approach to politics”
synonyms: practical, matter-of-fact, sensible, down-to-earth, commonsensical, businesslike, having both/one’s feet on
the ground, hardheaded, no-nonsense;

This is how Security Management should be done! Sensibly and realistically…

Bottom line is, do not leave someone hanging. If they have an inquiry, make sure it is properly and adequately answered before you sign off with them. Think for a minute about the following quote by Robert Estabrook:

 “He who has learned to disagree without being disagreeable has discovered the most valuable secret of a diplomat”

With that I want to conclude my article by encouraging Security Leaders of 2014 to say “Yes but” or “How” instead of “No”.

Thank you for reading, feel free to leave a comment!