secnote

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

README.md (2361B)



      1 # About secnote
      2 
      3 A tool to help mark sections in code as security critical or
      4 build code flows, all from within the code itself.
      5 
      6 ## Building
      7 
      8 ### platforms
      9 
     10 secnote should build on Linux distros like Ubuntu and Debian,
     11 on OpenBSD and on MacOS.
     12 
     13 ### requirements
     14 
     15 - libbsd-dev (on linux)
     16 - openssl / libressl
     17 - pkg-config
     18 
     19 ### build
     20 
     21 ```
     22   $ make
     23   $ make install
     24 ```
     25 
     26 ## How
     27 
     28 A secnote is opened with a @secnote-open marker.
     29 The open marker must include a topic and id.
     30 
     31 ```
     32   /* @secnote-open topic=a-topic id=unique-id-in-topic */
     33 ```
     34 
     35 The note is closed with a @secnote-close marker.
     36 
     37 ```
     38   /* @secnote-close */
     39 ```
     40 
     41 A note can have a weight attached to it. This is used by secnote
     42 for ordering the notes when multiple exist in the same topic.
     43 
     44 To do so, specify the weight after the topic name:
     45 
     46 ```
     47   /* @secnote-open topic=a-topic:100 ... */
     48 ```
     49 
     50 ## Show
     51 
     52 When running the tool without options on input files or directory it will
     53 gather information about the notes found and display them on stdout.
     54 
     55 ```
     56   $ secnote .
     57 ```
     58 
     59 You can also use options to display just a list of topics.
     60 
     61 ```
     62   $ secnote -l src include
     63 ```
     64 
     65 Or include all relevant locations.
     66 
     67 ```
     68   $ secnote -lf sys kern fs
     69 ```
     70 
     71 ## Verify
     72 
     73 The tool allows the notes to be dumped into a simple text-based database
     74 format, which allows a developer to verify these secnotes against new
     75 versions of the source code to see what security critical code has been
     76 altered.
     77 
     78 Create a secnote:
     79 
     80 ```
     81   $ secnote -d proj_1_0_0 > secnote.txt
     82 ```
     83 
     84 Verify the note against a new release:
     85 
     86 ```
     87   $ secnote -v secnote.txt proj_1_0_2
     88 ```
     89 
     90 You can also run secnote between 2 copies of the source:
     91 
     92 ```
     93   $ secnote -d proj_1_0_0 | secnote -p1 -v - proj_1_0_2
     94 ```
     95 
     96 ## Contribute
     97 
     98 Send patches to joris@coders.se.
     99 
    100 ## Caveats
    101 
    102 It is hard to classify certain parts of code as security critical
    103 while leaving out other parts.
    104 
    105 Security encompasses the entire code base.
    106 
    107 Secnote can make it easier to digest code and understand which parts of
    108 it relate to security or potentially even are security critical without
    109 intimate understanding of the code.
    110 
    111 As with everything related to comments and documentation, if it
    112 falls out of touch with reality it will become useless and could
    113 even turn into a security risk.
    114 
    115 Only accepts .c, .h and .py files, hackable though.
    116 
    117 ## License
    118 
    119 ISC licensed, created by Joris Vink.