'With Great Power...'

'With Great Power...'

Making security documentation that matters

Feb 1, 2023·

5 min read

Secure systems are important. We often hold precious information in our products and that needs to be protected.

There are several different approaches to ensuring good enough security in digital products. My go-to option is to place responsibility where the work is. Requiring the teams that own the products to own, understand and deliver securely.

That doesn't happen by magic. Teams need sufficient experience, information and support to make good choices. That's where great documentation fits in. Guidance and ease for engineers plays a big part in helping teams do security well.

In this blog post, I'll tell you why it's important and take a deep dive into an example I helped build.

Why Security Standards are important

Most engineering teams need assistance to own security - it's not their area of expertise. They need to understand security threats, and the protective solutions needed in their products. They also need a broader picture of how to operate online in this risky world and how to reason about threats.

Additionally, empowered product teams get very good at making trade-offs to get to market and find product-market fit. They need to know what's not negotiable, and when security might become more important as their product grows.

A document is no replacement for an expert, but it can scale, and be there whenever someone needs advice. It can cover the default and the quick wins, allowing experts to deal with more novel problems.

What a security standard needs to do

A Standard sets a bar. It says what needs to happen.

A good Standard presents solutions and safe ways to work: paved paths, pits of success, and guardrails. Low-friction, good defaults to avoid or solve the problems that the standard lays out.

A great Standard explains why. It enables teams to make the right choice in context and helps grow their experience. It might even ask them to contribute.

A useful Security Standard needs to do all these.

In the deep drive below you'll see a standard that does these, as well as present contact points, for when the standard isn't enough; guidance in structured thinking about risk and security, so folk are likely to make good decisions; ways to learn more about security, so that we can grow community.

Meet Stan, a Secure Engineering STANdard

It was nicknamed the STAN, after Stan Lee, the Marvel Comics' key creator. It has his phrase “With great power comes great responsibility” in large friendly letters on the cover.

This served as a reminder that empowered and autonomous teams have great freedom in their choices, but also a great responsibility to take good care of their users’ data.

The guide provided materials to help teams understand and think about the risks their products are exposed to. It also provides a structure to operate within to mitigate those risks.

How did the STAN do this?

The STAN was clear about what risks need to be managed...

The Stan presents a set of baseline risks that must always be managed. These Secure by Default Directives set up every product for security success. Every team must follow these directives when building software.

The STAN also contains a set of directives for higher-risk areas and advice on how to navigate them in a bespoke way.

The STAN offers readers a set of ‘secure by default’ directives that should be followed

...and provided solutions

Telling people the risks they need to protect against is not enough. The Stan made it easy for teams to solve these problems and manage these risks. It did this by providing a practice or solution for each directive.

The STAN guided choices through graded paths

There’s diminishing value in building more than you need. Teams should go fast when it’s safe to do so and take special care when it’s important.

The STAN contributed to this by presenting an operating model that avoids rules for rules’ sake. Simple, low-risk projects can ship swiftly with default levels of security. More complex and risky projects can be assessed and suitable security built in.

The STAN offed graded paved paths, based on the type of data being processed. If a product was assessed to be in a higher-risk category, the team was provided with a higher level of directives and practices.

The STAN asks readers to consider how much security they need

The STAN helped people think about managing risk

The distribution of security experience is often uneven. The STAN helped to level this and helped everyone think about what they should be doing to manage risk.

This included sections on Threat Modeling and thinking about risk, as well as guidance for learning more about security.

The STAN was a collaborative living document

The STAN was actively developed in collaboration with product engineers and was improved by their contributions and feedback.

Good defensive practices develop over time. The Stan was delivered iteratively. We didn't want to get everything perfect before shipping. We expected practices to change and invited discussion.

It was built in markdown in GitHub, where engineers spend a lot of time. It invited engineers to review, feedback and contribute in a form they already knew.

A standard can be impactful

Supporting product teams to make good and informed decisions means that a small Security team can have a big impact.

Creating a standard enables security teams to focus on adding value in more risky areas, safe in the knowledge that the basics are there.

Cover by Hello I'm Nik from Unsplash