Security Best Practices for Developers: Lessons from Sqreen's Open-Source Guide

Hook

Most security documentation is written by security experts for security experts—but developers are the ones writing the vulnerable code. Sqreen's DevelopersSecurityBestPractices repository attempts to bridge this gap, though with mixed results.

Context

The security industry has a communication problem. Traditional security documentation reads like legal compliance manuals, filled with abstract threats and theoretical attack vectors that feel distant from the day-to-day reality of shipping features. Developers need security guidance that speaks their language—practical, code-focused, and actionable during the development process, not after a breach.

Sqreen, a application security company later acquired by Datadog, created this repository to address that gap. Rather than another OWASP-style comprehensive security framework, they built a Jekyll-based static site that presents security best practices in a developer-friendly format. The goal was clear: make security accessible to the people who need it most—the developers writing code every day. However, with only 77 stars and minimal documentation, the project appears to have struggled with adoption despite coming from a reputable security vendor.

Technical Insight

The repository's architecture reflects a philosophy of simplicity over sophistication. At its core, it's a standard Jekyll static site generator implementation, processing Markdown files into HTML pages. Content authors write security guidelines in Markdown, Jekyll transforms them into static HTML, and the result is a fast, hostable documentation site that requires zero backend infrastructure.

The build system uses a dual-toolchain approach: Ruby/Bundler manages Jekyll dependencies while Node.js/Gulp handles CSS preprocessing with Stylus. Here's what a typical content structure looks like:

---
layout: default
title: Input Validation Best Practices
category: web-security
---

## Why Input Validation Matters

Every input is an attack vector. User input, API responses, 
file uploads—all require validation before processing.

### Common Mistakes

```javascript
// DON'T: Trust user input directly
app.post('/user', (req, res) => {
  db.query(`INSERT INTO users (name) VALUES ('${req.body.name}')`);
});

// DO: Use parameterized queries
app.post('/user', (req, res) => {
  db.query('INSERT INTO users (name) VALUES (?)', [req.body.name]);
});

This Markdown-first approach lowers the barrier for security professionals and developers to contribute content without wrestling with complex CMS systems or custom documentation frameworks. The Jekyll front matter allows for categorization and metadata without requiring database infrastructure.

The CSS build system uses Gulp to process Stylus files, which seems like over-engineering for a documentation site. A simpler setup might look like this in the Gulpfile:

```javascript
const gulp = require('gulp');
const stylus = require('gulp-stylus');

gulp.task('stylus', function() {
  return gulp.src('./stylesheets/*.styl')
    .pipe(stylus({ compress: true }))
    .pipe(gulp.dest('./css'));
});

gulp.task('watch', function() {
  gulp.watch('./stylesheets/**/*.styl', ['stylus']);
});

This dual-build system (Jekyll for content, Gulp for styles) adds complexity without clear benefits. Modern Jekyll supports Sass natively through its asset pipeline, making the Node.js dependency unnecessary. The choice to use Stylus specifically—a less common CSS preprocessor compared to Sass or Less—further increases the learning curve for potential contributors.

The real value proposition here isn't the technology stack but the content philosophy: security guidance presented in code-first examples rather than theoretical frameworks. Each article ideally shows vulnerable code alongside its secure counterpart, making the impact immediately visible. This pattern-based learning helps developers recognize security issues in their own codebases, not just understand abstract concepts.

The repository structure separates concerns cleanly: _posts/ contains the actual security articles, _layouts/ defines page templates, and stylesheets/ manages styling. This organization makes it easy to contribute new security topics without understanding the entire system—you just add a Markdown file in the right format.

Gotcha

The most significant limitation is documentation about the documentation. The repository lacks a comprehensive README explaining what security topics are covered, who the target audience is, and how the content is organized. You have to clone the repo and browse the _posts/ directory to discover what's actually included. For a resource meant to make security more accessible, this creates an ironic barrier to entry.

The dual-build system creates unnecessary complexity. Contributors need both Ruby and Node.js environments configured correctly, and the build process requires running both Jekyll and Gulp. This violates the principle of minimal tooling—a documentation site shouldn't require two different language runtimes. Modern alternatives like Hugo (single binary) or Jekyll with native Sass support would eliminate this friction. The low star count (77) despite coming from a reputable security company suggests this complexity may have hindered community contributions.

Maintenance appears stalled. With no clear indication of active development and minimal community engagement, the security recommendations may become outdated as languages and frameworks evolve. Security best practices for Node.js from three years ago don't account for newer attack vectors or modern framework features. Without active maintenance, this becomes a historical artifact rather than a living resource.

Verdict

Use if: You're looking for developer-oriented security examples from a reputable security vendor's perspective and want to see how to structure security documentation for developers. The Jekyll-based approach works well if you're already familiar with static site generators and want to fork this as a foundation for internal security guidelines. It's also useful if you prefer code-first security examples over abstract security frameworks. Skip if: You need comprehensive, actively-maintained security documentation with strong community support—OWASP's Developer Guide or Mozilla's Web Security Guidelines offer more extensive coverage and regular updates. Also skip if you want framework-specific guidance for modern JavaScript, Python, or Go ecosystems, as those communities have created better-maintained resources. The minimal documentation and stalled maintenance make this more of a reference implementation than a production-ready security resource.