portrait picture

TIMO ZIMMERMANN

balancing software engineering & infosec

Security 101: documentation – policies in disguise

posted on Saturday 7th of September 2019 in ,

There are a few things you will hear every start up chant about as if it was an absolute truth. The most prominent one is likely „move fast“ — meaning „all the talk about best practices etc does not apply to us; we have to ‚move fast‘ to make it“. While this might be true in a lot of cases, I have often seen it being a disadvantage, even in the short term.

It is likely that you can get away with a lot of short cuts. Code you write today is probably obsolete in a few months, maybe even in a few weeks. Deciding to cut corners when developing your asynchronous workers likely won’t matter until you have a lot more customers than you currently have. Having a configuration file checked into git, forcing you to redeploy on each config change, can be feasible for some time. Obviously all of the technical debt comes with a few exceptions though, like having your workers separated properly in your code base and not checking in secrets.

What I would advocate against most of the time is skipping documentation. It might be tempting to follow the narrative that documentation is just a burden to maintain and that it will be outdated in a few weeks, but this is purely an organisational problem. If you document features and processes as you build them it will likely only be a very minor point on your todo list when working on large changes. And maintaining documentation as part of your feature work means it will not be outdated (or simply wrong).

This also does not mean you should write prose for everything you do. Changing the way a button looks? I would not expect any documentation at all. Adding a circuit breaker when your email service of choice is down? A sentence in a change log should be sufficient. Developing a circuit breaker solution in house? A few lines as spec to have some guidelines around design decisions are fine.

There is also the sort of documentation you write once and then leave it unchanged for months, maybe years. How do you handle your code review process? Opening a merge request and two people have to approve a change? Maybe one? Is code merged into a staging branch first or directly into production? Just write it down. It is, again, a few sentences and you are done. While it might not be a one time investment, it is a relatively small part of the work you will be doing. And it likely will not delay your product roadmap significantly.

But what do you get in exchange for documenting features, changes and processes? In the end it is still time you are not working on shipping your actual product, right?

First of all: As you scale and grow your team you make onboarding a lot easier. You have a set of documents and resources you can point new employees to to get a basic understanding of how things are working. More senior engineers have a way to see the reasoning behind certain features and design decisions, which, as you grow, will potentially look less optimal when approaching a problem from a best practice point of view. One part that makes hiring expensive is not only sourcing and interviewing, but also onboarding. Being able to reduce your onboarding cost with small, continuous investments will pay off as you scale. Especially when you are forced to grow fast.

The other reason (and this is why it is part of the „security 101“ series!) is that most documentation can serve as policy.

I can already see my infosec colleagues with audit experience reaching for their torches, especially if they were recently going through one and got remediation plans containing „date format on policy X does not match the standard format“. But hear me out, there is actually some truth hidden in this statement.

Startups usually do not think a lot (if at all) about audits, certifications or external controls if they are not operating in a highly regulated environment like finance or healthcare. The day one of those things is required it is usually a panicky “all hands on deck”-situation that no one will have a good time with.

The most common scenario in which this might come up is a partnership with a larger enterprise or selling to another business. Companies will have something like an “vendor acquisition policy” which defines which standards a potential partner or vendor has to fulfil for the deal to go through. Many list SOC in one form or another or ISO27001 for example. The moment one or more certifications is on the requirements list to close a deal you can be sure you will either have to get the certification or the deal is off. There are only a few very rare cases I have seen when someone on the highest level of management whitelisted the deal despite unmet technical acquisition criteria.

Realistically speaking you will not even be close to fulfilling any of those certification requirements by simply documenting what you do, how you do it and what is happening to your system. But you will have a lot of the foundational work done – you do not have to do it last minute. You can, as larger deals sneak up, start looking at the certification requirements and see which processes might need some adjustments, were you are currently lacking documentation or processes and how much work it will be to get your system and company into a compliant state. Having an actionable list and work for which the effort can actually be estimated will be a huge help, especially when you can use it as base for communication with your potential partner to see if you can move forward while working on the last few things – believe it or not, this actually worked in the past.

Some certifications actually make sense. Some not so much. But nearly all have one purpose beside being a checklist item: They help instil trust. Selling to end user and consumers, they show that you actually care. They show that you want to be on the front-page of TechCrunch for shipping a new feature or closing a funding round, not because you leaked PII. While this is not the purpose of many certifications and while you can be fully compliant with a few and still mess up badly, they will instil trust.

Especially for end users and consumers it often does not matter what you actually do, but if they feel like they can trust you with their data. Many will not even know the certification you mention on your marketing page, but they will still feel better that you got one. This might sound wrong to some and be assured, so it does to me. This is not about logic or facts, this is about psychology, marketing and sales. Here, trust is a currency you cannot ignore.

Documenting your system and processes will help you on many different occasions. It is some additional work you have to do, but if you start early and make it part of your regular process it will only be a very small portion of the over all work. So better start today than on the day you need it. Future you will thank you. If you are unsure how and what to document, do not worry, I will cover that in depth in future posts.

If you want to follow this article series you can either subscribe to the general RSS feed or to the tag specific one if you only care about startup security posts.