secnote

The secnote tool.
Commits | Files | Refs | README | LICENSE | git clone https://git.kore.io/secnote

commit c6932bc8486a4ff70dab2b323d477326ee9af0fd
parent b7df9b0beaa6663a8de86871f5935b428dd0f552
Author: Joris Vink <joris@coders.se>
Date:   Tue, 14 Jun 2022 13:22:15 +0200

Update README a bit.

Diffstat:
README.md | 61+++++++++++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 53 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md @@ -1,20 +1,65 @@ -# secnote +# What is secnote? -WIP +A tool to help mark sections in code as security critical or build +code flows, all from within the code itself. -## notes +# A secnote -There may be different reasons for marking a section of code as -a secnote. Perhaps a design decision, or a belt and suspender. +A secnote is opened with a @secnote-open marker. + +The open marker must include a topic and id. + + /* @secnote-open topic=a-topic id=unique-id-in-topic */ + ... + +The note is closed with a @secnote-close marker. + + /* @secnote-close + +# Show + +When running the tool without options on input files or directory it will +gather information about the notes found and display them on stdout. + + $ secnote . + +You can also use options to display just a list of topics. + + $ secnote -l src include + +Or include all relevant locations. + + $ secnote -lf sys kern fs + +# Verify + +The tool allows the notes to be dumped into a simple text-based database +format, which allows a developer to verify these secnotes against new +versions of the source code to see what security critical code has been +altered. + +Create a secnote: + + $ secnote -d proj_1_0_0 > secnote.txt + +Verify the note against a new release: + + $ secnote -v secnote.txt proj_1_0_2 + +You can also run secnote between 2 copies of the source: + + $ secnote -d proj_1_0_0 | secnote -p1 -v - proj_1_0_2 + +## Caveats It is hard to classify certain parts of code as security critical while leaving out other parts. Security encompasses the entire code base. -However, secnote should make it easier to digest code and -understand which parts of it relate to security or potentially -even are security critical without intimate understanding of the code. +Secnote can make it easier to digest code and understand which parts of +it relate to security or potentially even are security critical without +intimate understanding of the code. As with everything related to comments and documentation, if it falls out of touch with reality it will become useless and could