Author: Joris Vink <email@example.com>
Date: Tue, 14 Jun 2022 13:22:15 +0200
Update README a bit.
|README.md|| | ||61||+++++++++++++++++++++++++++++++++++++++++++++++++++++--------|
1 file changed, 53 insertions(+), 8 deletions(-)
diff --git a/README.md b/README.md
@@ -1,20 +1,65 @@
+# What is secnote?
+A tool to help mark sections in code as security critical or build
+code flows, all from within the code itself.
+# 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
+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
+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
+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
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