Merge pull request #9 from TerribleDev/docs

add docs

Readme.md

@@ -2,7 +2,7 @@
 
 <img src="Hat.png" width="350px"/>
 
-HardHat is a set of .net core middleware that adds various headers to help protect your site from vulnerabilities. Inspired by [helmetJS](https://helmetjs.github.io). Currently in beta, documentation due before 1.0.0. Even still, this should work fine.
+HardHat is a set of .net core middleware that adds various headers to help protect your site from vulnerabilities. Inspired by [helmetJS](https://helmetjs.github.io). We have [some docs](docs/Readme.md) they are still a work in progress, so please feel free to submit changes to them.
 
 
 In short this allows:

docs/ContentSecurityPolicy.md

@@ -0,0 +1,31 @@
+sets the `Content-Security-Policy` header which can help protect against malicious injection of JavaScript, CSS, plugins, and more.
+
+
+## Attack
+
+When hackers can place content onto your site, they can do bad things! For example, javascript executing can give them someones credit card data. Or they could place a 1x1 transparent gif on your site to collect data.
+
+
+## The Header
+
+The `Content-Security-Policy` header tells browsers which domains content can come from. This is essentially a white list of domains where content can be loaded. For example, images could only come from your images subdomain.
+
+## Code 
+
+Here we are saying images can come from any subdomain of my site. Fonts can come from the current domain.
+
+```csharp
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+                app.UseContentSecurityPolicy(
+                new ContentSecurityPolicyBuilder()
+                .WithDefaultSource(CSPConstants.Self)
+                .WithImageSource("http://*.mysite.com")
+                .WithFontSource(CSPConstants.Self)
+                .WithFrameAncestors(CSPConstants.None)
+                .BuildPolicy()
+               );
+}
+
+```

docs/CrossSiteScripting.md

@@ -0,0 +1,21 @@
+The Cross Site Scripting filter sets the `X-XSS-Protection` to prevent reflected XSS attacks
+
+## Attack
+
+If someone can run JavaScript on your page, they can attack your users and do a lot of bad things. Sometimes people can inject script tags through query strings, and thus attack your users
+
+## The Header
+
+This middleware simply allows the browsers to detect and combat reflective XSS attacks. This will not save you against all attacks, but its a good start. Note in older versions of IE, this causes more security issues so we turn it off.
+
+## Code 
+
+```csharp
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    app.UseCrossSiteScriptingFilters();
+    //app.UseCrossSiteScriptingFilters(addOldIE: true); if you want older versions of IE to get the header
+}
+
+```

docs/DnsPrefetch.md

@@ -0,0 +1,21 @@
+DNS Prefetch sets the `X-DNS-Prefetch-Control`
+
+## Attack
+
+When you visit a URL, the browser prefetches dns for a given link. This is a performance improvement, but can expose your users privacy by having them visit sites, they have never visited.
+
+
+## The Header
+
+The `X-DNS-Prefetch-Control` header tells browsers whether they should do DNS prefetching. 
+
+## Code 
+
+```csharp
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    app.UseDnsPrefetch(allow: false);
+}
+
+```

docs/Frameguard.md

@@ -0,0 +1,23 @@
+Frameguard mitigates clickjacking attacks by setting the `X-Frame-Options` header.
+
+## Attack
+
+Attackers get you to click on something you do not wish to click on. Often they do this by iframing other website, buttons but with a different context.
+
+For example lets say your button says you are only going to vote democrat, hackers may make a website that says you will only vote republican and iFrame your button in their website.
+
+
+## The Header
+
+The `X-Frame-Options` header tells browsers to prevent your webpage from being put in an iframe. This can also control which domains are allowed to load iframes from your site.
+
+## Code 
+
+```csharp
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    app.UseFrameGuard(new FrameGuardOptions("http://amazon.com"));
+}
+
+```

docs/Hpkp.md

@@ -0,0 +1,30 @@
+the HTTP Public Key Pinning module helps you set the `Public-Key-Pins` header to prevent person-in-the-middle attacks.
+
+## Attack
+
+If hackers can intercept secure requests to your website, they can gain credit card information, or passwords of your customers.
+
+
+## The Header
+
+The `Public-Key-Pins` header gives the browsers a hash of your public keys. This verifies to the browser if they are actually talking to your website
+
+## Code 
+
+You can set the max age of the cache in seconds. You provide base64 encoded keys, and 
+
+```csharp
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+            app.UseHpkp(maxAge: 5184000, 
+            keys: new List<PublicKeyPin>{
+                new PublicKeyPin("cUPcTAZWKaASuYWhhneDttWpY3oBAkE3h2+soZS7sWs=", HpKpCrypto.sha256),
+                new PublicKeyPin("M8HztCzM3elUxkcjR2S5P4hhyBNf6lHkmjAHKhpGPWE=", HpKpCrypto.sha256)
+            }, 
+            includeSubDomains: true, 
+            reportUri: "/report", 
+            reportOnly: false);
+}
+
+```

docs/Hsts.md

@@ -0,0 +1,25 @@
+Set the `Strict-Transport-Security` header which tells the browser to use https
+
+## Attack
+
+Most websites only want to server over https, but often a http request is made and a user is redirected to https. This middleware caches the knowledge to use https, so future http requests cannot be man in the middle attacked
+
+
+## The Header
+
+the `Strict-Transport-Security` header controls the browsers behavior to default to https
+
+## Code 
+
+
+Apart from setting a max age, you can include your subdomains. Ontop of all, you can include a preload header, which is required if you submit your [site to google](https://hstspreload.org/). Submitting your site to google will mean that the hsts header will be cached in the browsers ahead of time. 
+
+```csharp
+
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    app.UseHsts(maxAge: 5000, includeSubDomains: true, preload: false);
+}
+
+```

docs/IENoOpen.md

@@ -0,0 +1,21 @@
+Prevent IE from opening websites in the context of your site
+
+## Attack
+
+In old versions of IE, IE would open html files in the context of your site. Lets say you uploaded a html file as your image for your profile picture in a social media site. Old versions of IE would actually render the html out!
+
+
+## The Header
+
+The `X-Download-Options` header can be set to noopen.
+
+## Code 
+
+```csharp
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    app.UseIENoOpen();
+}
+
+```

docs/MimeSniff.md

@@ -0,0 +1,21 @@
+the Don’t Sniff Mimetype middleware, noSniff, helps prevent browsers from trying to guess ("sniff") the MIME type.
+
+## Attack
+
+Some browsers will detect what the mime type of a file is, even if the webserver says something else. Lets say someone uploads a script file to your website as their profile. Even though the webserver could say the mime type is one thing, the browser could interpret it as javascript and execute it!
+
+
+## The Header
+
+The `X-Content-Type-Options` header can be set to `nosniff` to prevent mime sniffing.
+
+## Code 
+
+```csharp
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    app.UseNoMimeSniff();
+}
+
+```

docs/Readme.md

@@ -0,0 +1,16 @@
+## Index
+
+Hard hat is essentially a group of 12+ individual middleware that help you improve the security of your aspnet core based applications.
+
+Each middleware has a seperate readme file. These docs were inspired by helmetjs.
+
+
+* [DnsPrefetch](DnsPrefetch.md)  controls browser DNS prefetching
+* [Cross Site Scripting](CrossSiteScripting.md) prevent reflective xss attacks
+* [Content Security Policy](ContentSecurityPolicy.md) 
+* [FrameGuard](Frameguard.md) prevent clickjacking
+* [HpKp](Hpkp.md)  for http public key pinning
+* [Hsts](Hsts.md) for telling the browsers to always use https
+* [IENoOpen](IENoOpen.md) Prevents IE from opening websites in the context of your browsers
+* [MimeSniff](MimeSniff.md) Prevents the browsers from sniffing the mime type of a file
+* [ReferrerPolicy](ReferrerPolicy.md) Remove the referral header on link clicks 

docs/ReferrerPolicy.md

@@ -0,0 +1,21 @@
+ the Referrer Policy middleware can control the behavior of the `Referer header` by setting the `Referrer-Policy` header.
+
+## Attack
+
+The referrer header is usually set by the browsers to tell websites where users are coming from. This causes privacy issues for your users by telling other sites where they are coming from.
+
+
+## The Header
+
+The `Referrer-Header` header can be set to `no-referrer` to prevent such behaviors. The header can also be set to `same-origin` to track users between your own site
+
+## Code 
+
+```csharp
+
+public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
+{
+    app.UseReferrerPolicy(ReferrerPolicy.NoReferrer);
+}
+
+```