Initial commit

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 spearbit-audits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Readme.md

@@ -0,0 +1,21 @@
+# A Markdown based template for writing audit reports
+## Requirements
+1. [Pandoc](https://pandoc.org/)
+2. [Pandocfilters](https://github.com/jgm/pandocfilters): `pip install pandocfilters`.
+3. [LaTeX toolchain](https://www.latex-project.org/get/). We recommend a full install of LaTeX (installing individual `.sty` files are hard).
+4. [Pygments](https://pygments.org/): `pip install pygments`.
+5. bash
+
+## Manual Changes
+
+Manually update `title.tex` and `summary.tex`.
+
+## Generating the PDF
+
+*Manually*: Run `./generate.sh`. The report would be generated 
+
+*CI*: There is a github action that generates the PDF.
+
+1. Go to `Actions`, click on the last workflow.
+2. `Artifacts` -> `Spearbit.pdf`: a ZIP file containing the pdf.
+

generate.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# pandoc with gfm flavored markdown seems to have issues regarding
+# Skipping --from gfm here
+# pandoc summary.md -o summary.tex
+pandoc --filter pandoc-minted.py --from gfm report.md -o report.tex
+# A temporary work around to have page breaks.
+# FIXME figure out a way to natively do this.
+sed -i 's/textbackslash clearpage/clearpage/g' report.tex
+# On github CI, pandoc seems to be generating the following
+sed -i 's/textbackslash{}clearpage/clearpage/g' report.tex
+pdflatex -shell-escape -interaction nonstopmode main.tex
+# Running it a second time to generate references
+pdflatex -shell-escape -interaction nonstopmode main.tex

main.tex

@@ -0,0 +1,55 @@
+% An extension of article to include 17pt font size
+\documentclass[14pt]{extarticle}
+
+\usepackage[T1]{fontenc}
+
+
+\usepackage{helvet}
+\renewcommand{\familydefault}{\sfdefault}
+% \usepackage[helvet]{sfmath}
+% \everymath={\sf}
+
+\usepackage{parskip}
+
+\usepackage[english]{babel}	
+\usepackage[left=2cm, right=2cm, top=2cm, bottom=2cm]{geometry}
+
+ % Math packages
+\usepackage{amsmath,amsfonts,amsthm}
+
+\usepackage[pdftex]{graphicx}	
+
+% For hyphenation of texttt:
+% https://tex.stackexchange.com/questions/299/how-to-get-long-texttt-sections-to-break
+\usepackage[htt]{hyphenat}
+
+% For syntax highlighting
+\usepackage{minted}
+\setminted[]{frame=single,fontsize=\small,samepage=true,breaklines=true}
+% For links
+\usepackage[hyphens]{url}
+\PassOptionsToPackage{hyphens}{url}\usepackage[hidelinks]{hyperref}
+
+% Fixing a pandoc related error
+% https://tex.stackexchange.com/questions/257418/error-tightlist-converting-md-file-into-pdf-using-pandoc
+\def\tightlist{}
+
+\usepackage{longtable}
+
+% Adding breaklines=true to minted's settings seems to produce some errors related to fonts. This is
+% the only fix that worked.
+% https://stackoverflow.com/questions/70075331/pdflatex-file-cmss10-t3-cannot-open-type-1-font-file-for-read
+
+\pdfmapfile{-mpfonts.map}
+
+\begin{document}
+
+\include{title.tex}
+
+\include{summary.tex}
+
+\tableofcontents
+
+\include{report.tex}
+
+\end{document}

pandoc-minted.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python
+''' A pandoc filter that has the LaTeX writer use minted for typesetting code.
+
+Usage:
+    pandoc --filter ./minted.py -o myfile.tex myfile.md
+'''
+
+from string import Template
+from pandocfilters import toJSONFilter, RawBlock, RawInline
+
+
+def unpack_code(value, language):
+    ''' Unpack the body and language of a pandoc code element.
+
+    Args:
+        value       contents of pandoc object
+        language    default language
+    '''
+    [[_, classes, attributes], contents] = value
+
+    if len(classes) > 0:
+        language = classes[0]
+
+    attributes = ', '.join('='.join(x) for x in attributes)
+
+    return {'contents': contents, 'language': language,
+            'attributes': attributes}
+
+
+def unpack_metadata(meta):
+    ''' Unpack the metadata to get pandoc-minted settings.
+
+    Args:
+        meta    document metadata
+    '''
+    settings = meta.get('pandoc-minted', {})
+    if settings.get('t', '') == 'MetaMap':
+        settings = settings['c']
+
+        # Get language.
+        language = settings.get('language', {})
+        if language.get('t', '') == 'MetaInlines':
+            language = language['c'][0]['c']
+        else:
+            language = None
+
+        return {'language': language}
+
+    else:
+        # Return default settings.
+        return {'language': 'text'}
+
+
+def minted(key, value, format, meta):
+    ''' Use minted for code in LaTeX.
+
+    Args:
+        key     type of pandoc object
+        value   contents of pandoc object
+        format  target output format
+        meta    document metadata
+    '''
+    if format != 'latex':
+        return
+
+    # Determine what kind of code object this is.
+    if key == 'CodeBlock':
+        template = Template(
+            '\\begin{minted}[$attributes]{$language}\n$contents\n\end{minted}'
+        )
+        Element = RawBlock
+    else:
+        return
+
+    settings = unpack_metadata(meta)
+
+    code = unpack_code(value, settings['language'])
+
+    return [Element(format, template.substitute(code))]
+
+
+if __name__ == '__main__':
+    toJSONFilter(minted)
+

report.md

@@ -0,0 +1,50 @@
+# Spearbit
+
+Spearbit is a decentralized network of expert Web3 security engineers. Together, we help secure the Web3 ecosystem. We offer security reviews and related services to Web3 projects. Our  network has experience at every part of the stack, including protocol design, smart contracts, and the Solidity compiler itself. Spearbit brings in untapped security talent: expert freelance auditors want flexibility to work on interesting projects together. Learn more about us at https://spearbit.com.
+
+# Introduction
+
+<!-- TODO  -->
+Some introduction on the protocol
+
+The focus of the security review was on the following:
+
+1. Specific security concern 1.
+2. Specific security concern 2.
+3. Specific security concern 3.
+
+*Disclaimer*: This security review does not guarantee against a hack. It is a snapshot in time of brink according to the specific commit by a three person team. Any modifications to the code will require a new security review.
+
+# Findings 
+
+## High Severity
+### Actual Issue
+
+**Severity**: Low, Gas optimization
+
+Context: [`Contract.sol#L160-L165`](https://github.com/actuallink)
+
+```solidity
+contract Test {
+}
+```
+
+**Recommendation**:
+
+**Project**: Fixed in [PR #1](Https://github.com/actuallink).
+
+**Spearbit**: Resolved.
+
+## Medium Severity
+
+## Low Severity
+
+
+# Additional Comments
+
+
+<!-- A template hack to generate a newline in LaTeX -->
+\clearpage
+
+# Appendix
+

summary.tex

@@ -0,0 +1,51 @@
+\hypertarget{executive-summary}{%
+\section{Executive Summary}\label{executive-summary}}
+
+% FIXME
+Over the course of X days in total, \href{https://protocolname.come}{Protocolname} engaged with
+\href{https://spearbit.com}{Spearbit} to review
+% FIXME
+\href{https://github.com/permalink-to-protocolname}{Protocolname protocol}. 
+
+We found a total of X issues with Protocolname. 
+
+\begin{longtable}[c]{|l|l|}
+\hline \textbf{Repository} & \textbf{Commit} \\
+
+\hline
+% FIXME
+\href{https://github.com/permalink}{Projectname} &
+% FIXME The commit hash
+\href{https://github.com/permalink/commit/commithash}{commithash} \\
+\hline
+\end{longtable}
+
+\begin{longtable}[]{|l|l|}
+
+\caption*{\textbf{Summary}}
+% FIXME
+\hline Type of Project & TYPE \\   
+% FIXME
+\hline Timeline & Feb 29, 2022 - Feb 31, 2022   \\
+% FIXME
+\hline Methods & Manual Review \\
+% FIXME
+\hline Documentation & High \\
+% FIXME
+\hline Testing Coverage & High  \\
+\hline
+\end{longtable}
+
+
+\begin{longtable}[]{|l|l|}
+\caption*{\textbf{Total Issues}}
+% FIXME
+\hline High Risk & 1 \\
+% FIXME
+\hline Medium Risk & 0 \\ 
+% FIXME
+\hline Low Risk & 0 \\
+\hline Gas Optimizations and Informational & 0 \\
+\hline
+\end{longtable}
+

title.tex

@@ -0,0 +1,41 @@
+\begin{titlepage}
+  \vbox{}
+  \vbox{}
+
+  \begin{center}
+
+
+    % \vbox{ }
+    % Tittel
+    \noindent\makebox[\linewidth]{\rule{.7\paperwidth}{.6pt}}\\[0.7cm]
+
+    { \huge \bfseries
+
+      % FIXME: The project name
+      Protocolname Security Review
+    }\\[0.25cm]
+
+    \noindent\makebox[\linewidth]{\rule{.7\paperwidth}{.6pt}}\\[0.7cm]
+
+    % If subtitle is needed
+    % \large{Engagement II
+    % }\\[1.2 cm]
+
+    \vfill
+
+    \includegraphics[width=0.40\textwidth]{img/spearbit_wordmark_black.png}
+
+
+    \large
+    {\bfseries Reviewers}\\
+
+    % FIXME 
+    Reviewer 1, Lead \\
+    Reviewer 2, Lead \\
+    Reviewer 3, Researcher
+
+    {\large \today}
+
+  \end{center}
+
+\end{titlepage}