I'm working with the infamous Frank Heidt, George Gal and Jonathan Bailey to create a suite of modular, task-based security code examples. They happen to be experts at finding mistakes in code. Part of making good code is knowing what bad code looks like and more importantly what makes it bad, or what the trade-offs are. I've also pulled in Prashant Bansode from my core security team to help push the envelope on making the examples consumable. Prashant doesn't hold back when it comes to critical analysis and that's what we like about him.
For this exercise, I'm time-boxing the effort to see what value we produce within the time-box. We carved out a set of candidate code examples by identifying common mistakes in key buckets, including input/data validation, authentication, authorization, auditing and logging, exception management and a few others. We then prioritized the list and do daily drops of code. The outcome should be some useful examples and an approach for others to contribute examples.
Sharing a chunk of code is easy. We quickly learned that sharing insights with the code is not. Exposing the thinking behind the code is the real value. We want to make that repeatable. I think the key is a schema with test cases.
Here's our emerging schema and test cases ....
Code Example Schema (Short Form)
- Applies To
- Solution Example
- Problem Example
- Test Case
- Expected Results
- More Information
- Additional Resources
For more information on the schema and test cases, see Code Example Schema for Sharing Code Insights.
Today we had a deeply insightful review with Tom Hollander, Jason Taylor, and Paul Saitta. Jason and Paul are on site while we're solving another class of problems for customers. They each brought a lot to the table and collectively I think we have a much better understanding of what makes a good, reusable piece of code.
We made an important decision to optimize around "show me the code" and then explain it, versus a lot of build up and then the code. Our emerging schema has its limits and does not take the place of a How To or guidelines or a larger resuable block of code, but it will definitely help as we try to share more modular code examples that demonstrate proven practices.