BinaryDefense.FSharp.Analyzers

What?

This is a set of security analyzers for the FSharp Language using the FSharp Analyzers SDK.

Currently supported analyzers

• Hashing
  • Looks for MD5 creation
  • Looks for SHA1 creation

Why?

Detecting security issues early in your codebase can save your company from embarrassment or financial repercussions.

Also, there's growing need for security based tools in the FSharp ecosystem. Many tools cover CSharp projects but not FSharp. This project seeks to remedy that.

How?

1 - Install the analyzer using paket

Use paket to install the analyzer into a specialized Analyzers dependency group like this:

paket add BinaryDefense.FSharp.Analyzers.Hashing --group Analyzers

DO NOT use storage:none because we want the analyzer package to be downloaded physically into packages/analyzers directory.

2.a - Enable analyzers in Ionide

Make sure you have these settings in Ionide for FSharp

{
    "FSharp.enableAnalyzers": true,
    "FSharp.analyzersPath": [
        "./packages/analyzers"
    ]
}

2.b - Install the fsharp-analyzers tool

dotnet tool add fsharp-analyzers
dotnet tool restore

Then run it against your project

dotnet fsharp-analyzers --project ./src/MyLibrary/MyLibrary.fsproj

NuGet

Package	Stable	Prerelease
BinaryDefense.FSharp.Analyzers.Hashing

Developing

Make sure the following requirements are installed on your system:

• dotnet SDK 3.0 or higher
• Mono if you're on Linux or macOS.

or

• VSCode Dev Container

Environment Variables

• CONFIGURATION will set the configuration of the dotnet commands. If not set, it will default to Release.
  • CONFIGURATION=Debug ./build.sh will result in -c additions to commands such as in dotnet build -c Debug
• GITHUB_TOKEN will be used to upload release notes and Nuget packages to GitHub.
  • Be sure to set this before releasing
• DISABLE_COVERAGE Will disable running code coverage metrics. AltCover can have severe performance degradation so it's worth disabling when looking to do a quicker feedback loop.
  • DISABLE_COVERAGE=1 ./build.sh

Building

> build.cmd <optional buildtarget> // on windows
$ ./build.sh  <optional buildtarget>// on unix

The bin of your library should look similar to:

$ tree src/MyCoolNewLib/bin/
src/MyCoolNewLib/bin/
└── Debug
    ├── net461
    │   ├── FSharp.Core.dll
    │   ├── MyCoolNewLib.dll
    │   ├── MyCoolNewLib.pdb
    │   ├── MyCoolNewLib.xml
    └── netstandard2.1
        ├── MyCoolNewLib.deps.json
        ├── MyCoolNewLib.dll
        ├── MyCoolNewLib.pdb
        └── MyCoolNewLib.xml

Build Targets

• Clean - Cleans artifact and temp directories.
• DotnetRestore - Runs dotnet restore on the solution file.
• DotnetBuild - Runs dotnet build on the solution file.
• DotnetTest - Runs dotnet test on the solution file.
• GenerateCoverageReport - Code coverage is run during DotnetTest and this generates a report via ReportGenerator.
• WatchTests - Runs dotnet watch with the test projects. Useful for rapid feedback loops.
• GenerateAssemblyInfo - Generates AssemblyInfo for libraries.
• DotnetPack - Runs dotnet pack. This includes running Source Link.
• SourceLinkTest - Runs a Source Link test tool to verify Source Links were properly generated.
• PublishToNuGet - Publishes the NuGet packages generated in DotnetPack to NuGet via paket push.
• GitRelease - Creates a commit message with the Release Notes and a git tag via the version in the Release Notes.
• GitHubRelease - Publishes a GitHub Release with the Release Notes and any NuGet packages.
• FormatCode - Runs Fantomas on the solution file.
• BuildDocs - Generates Documentation from docsSrc and the XML Documentation Comments from your libraries in src.
• WatchDocs - Generates documentation and starts a webserver locally. It will rebuild and hot reload if it detects any changes made to docsSrc files, libraries in src, or the docsTool itself.
• ReleaseDocs - Will stage, commit, and push docs generated in the BuildDocs target.

• Release - Task that runs all release type tasks such as PublishToNuGet, GitRelease, ReleaseDocs, and GitHubRelease. Make sure to read Releasing to setup your environment correctly for releases.

Releasing

• Start a git repo with a remote

git add .
git commit -m "Scaffold"
git remote add origin https://github.com/user/MyCoolNewLib.git
git push -u origin master

• Add your NuGet API key to paket

paket config add-token "https://www.nuget.org" 4003d786-cc37-4004-bfdf-c4f3e8ef9b3a

• Create a GitHub OAuth Token

  • You can then set the GITHUB_TOKEN to upload release notes and artifacts to github
  • Otherwise it will fallback to username/password

• Then update the RELEASE_NOTES.md with a new version, date, and release notes ReleaseNotesHelper

#### 0.2.0 - 2017-04-20
- FEATURE: Does cool stuff!
- BUGFIX: Fixes that silly oversight

• You can then use the Release target. This will:
  • make a commit bumping the version: Bump version to 0.2.0 and add the release notes to the commit
  • publish the package to NuGet
  • push a git tag

./build.sh Release