Merge pull request #19 from benmccallum/patch-1

Avoid XSS by escaping HTML during serialization

Author: RehanSaeed

README.md

@@ -1,4 +1,4 @@
-![Schema.NET Banner](https://raw.githubusercontent.com/RehanSaeed/Schema.NET/master/Images/Banner.png)
+![Schema.NET Banner](https://raw.githubusercontent.com/RehanSaeed/Schema.NET/master/Images/Banner.png)
 
 Schema.org objects turned into strongly typed C# POCO classes for use in .NET. All classes can be serialized into JSON/JSON-LD and XML, typically used to represent structured data in the `head` section of `html` page.
 
@@ -16,7 +16,7 @@ var jsonLd = website.ToString();
 
 The code above outputs the following JSON-LD:
 
-```JSONLD
+```JSON
 {
     "@context":"http://schema.org",
     "@type":"WebSite",
@@ -26,6 +26,8 @@ The code above outputs the following JSON-LD:
 }
 ```
 
+If writing the result into a `<script>` element, be sure to use the `.ToHtmlEscapedString()` method instead to avoid exposing your website to a Cross-Site Scripting attack. See the [example below](#important-security-notice).
+
 ## What is Schema.org?
 
 [schema.org](https://schema.org) defines a set of standard classes and their properties for objects and services in the real world. This machine readable format is a common standard used across the web for describing things.
@@ -56,6 +58,17 @@ Using structured data in `html` requires the use of a `script` tag with a MIME t
 </script>
 ```
 
+##### Important Security Notice
+When serializing the result for a website's `<script>` tag, you should use the alternate `.ToHtmlEscapedString()` to avoid exposing yourself to a Cross-Site Scripting (XSS) vulnerability if some of the properties in your schema have been set from untrusted sources.
+Usage in an ASP.NET MVC project might look like this:
+
+```HTML
+<script type="application/ld+json">
+    @Html.Raw(Model.Schema.ToHtmlEscapedString())
+</script>
+```
+ 
+
 #### Windows UWP Sharing
 
 Windows UWP apps let you share data using schema.org classes. [Here](https://docs.microsoft.com/en-us/uwp/schemas/appxpackage/appxmanifestschema/element-sharetarget) is an example showing how to share metadata about a book.

Source/Schema.NET/Thing.Partial.cs

@@ -1,4 +1,4 @@
-namespace Schema.NET
+namespace Schema.NET
 {
     using System.Collections.Generic;
     using System.Text;
@@ -8,6 +8,10 @@
     public partial class Thing : JsonLdObject
     {
         private const string ContextPropertyJson = "\"@context\":\"http://schema.org\",";
+
+        /// <summary>
+        /// Default serializer settings used.
+        /// </summary>
         private static readonly JsonSerializerSettings SerializerSettings = new JsonSerializerSettings()
         {
             Converters = new List<JsonConverter>()
@@ -17,14 +21,54 @@ public partial class Thing : JsonLdObject
             NullValueHandling = NullValueHandling.Ignore
         };
 
+        /// <summary>
+        /// Serializer settings used when trying to avoid XSS vulnerabilities where user-supplied data is used
+        /// and the output of the serialization is embedded into a web page raw.
+        /// </summary>
+        private static readonly JsonSerializerSettings HtmlEscapedSerializerSettings = new JsonSerializerSettings()
+        {
+            Converters = new List<JsonConverter>()
+            {
+                new StringEnumConverter()
+            },
+            NullValueHandling = NullValueHandling.Ignore,
+            StringEscapeHandling = StringEscapeHandling.EscapeHtml
+        };
+
         /// <summary>
         /// Returns the JSON-LD representation of this instance.
         /// </summary>
         /// <returns>
         /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
         /// </returns>
-        public override string ToString() =>
-            RemoveAllButFirstContext(JsonConvert.SerializeObject(this, SerializerSettings));
+        public override string ToString() => this.ToString(SerializerSettings);
+
+        /// <summary>
+        /// Returns the JSON-LD representation of this instance.
+        ///
+        /// This method should be used when you want to embed the output raw (as-is) into a web
+        /// page. It uses serializer settings with HTML escaping to avoid Cross-Site Scripting (XSS)
+        /// vulnerabilities if the object was constructed from an untrusted source.
+        /// </summary>
+        /// <returns>
+        /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
+        /// </returns>
+        public string ToHtmlEscapedString() => this.ToString(HtmlEscapedSerializerSettings);
+
+        /// <summary>
+        /// Returns the JSON-LD representation of this instance using the <see cref="JsonSerializerSettings"/> provided.
+        ///
+        /// Caution: You should ensure your <paramref name="serializerSettings"/> has
+        /// <see cref="JsonSerializerSettings.StringEscapeHandling"/> set to <see cref="StringEscapeHandling.EscapeHtml"/>
+        /// if you plan to embed the output using @Html.Raw anywhere in a web page, else you open yourself up a possible
+        /// Cross-Site Scripting (XSS) attack if untrusted data is set on any of this object's properties.
+        /// </summary>
+        /// <param name="serializerSettings">Serialization settings.</param>
+        /// <returns>
+        /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
+        /// </returns>
+        public string ToString(JsonSerializerSettings serializerSettings) =>
+            RemoveAllButFirstContext(JsonConvert.SerializeObject(this, serializerSettings));
 
         private static string RemoveAllButFirstContext(string json)
         {

Tests/Schema.NET.Test/JobPostingTest.cs

@@ -10,7 +10,7 @@ public class JobPostingTest
         private readonly JobPosting jobPosting = new JobPosting()
         {
             Title = "Fitter and Turner", // Required
-            Description = "<p>Widget assembly role for pressing wheel assemblies.</p><p><strong>Educational Requirements:</strong> Completed level 2 ISTA Machinist Apprenticeship.</p><p><strong>Required Experience:</strong> At least 3 years in a machinist role.</p>", // Required
+            Description = "Widget assembly role for pressing wheel assemblies. Educational Requirements: Completed level 2 ISTA Machinist Apprenticeship. Required Experience: At least 3 years in a machinist role.", // Required
             Identifier = new PropertyValue() // Recommended
             {
                 Name = "MagsRUs Wheel Company",
@@ -51,7 +51,7 @@ public class JobPostingTest
             "\"@context\":\"http://schema.org\"," +
             "\"@type\":\"JobPosting\"," +
             "\"title\":\"Fitter and Turner\"," +
-            "\"description\":\"<p>Widget assembly role for pressing wheel assemblies.</p><p><strong>Educational Requirements:</strong> Completed level 2 ISTA Machinist Apprenticeship.</p><p><strong>Required Experience:</strong> At least 3 years in a machinist role.</p>\"," +
+            "\"description\":\"Widget assembly role for pressing wheel assemblies. Educational Requirements: Completed level 2 ISTA Machinist Apprenticeship. Required Experience: At least 3 years in a machinist role.\"," +
             "\"identifier\":{" +
                 "\"@type\":\"PropertyValue\"," +
                 "\"name\":\"MagsRUs Wheel Company\"," +

Tests/Schema.NET.Test/SerializationTest.cs

@@ -0,0 +1,97 @@
+namespace Schema.NET.Test
+{
+    using System;
+    using System.Collections.Generic;
+    using Newtonsoft.Json;
+    using Newtonsoft.Json.Converters;
+    using Xunit;
+
+    // https://developers.google.com/search/docs/data-types/books
+    public class SerializationTest
+    {
+        private static readonly Person Person = new Person()
+        {
+            Name = "J.D. Salinger</script><script>alert('gotcha');</script>",
+            Description = null
+        };
+
+        private readonly Book book = new Book()
+        {
+            Id = new Uri("http://example.com/book/1"),
+            Name = "The Catcher in the Rye</script><script>alert('gotcha');</script>",
+            Author = Person
+        };
+
+        private readonly string json =
+        "{" +
+            "\"@context\":\"http://schema.org\"," +
+            "\"@type\":\"Book\"," +
+            "\"@id\":\"http://example.com/book/1\"," +
+            "\"name\":\"The Catcher in the Rye</script><script>alert('gotcha');</script>\"," +
+            "\"author\":{" +
+                "\"@type\":\"Person\"," +
+                "\"name\":\"J.D. Salinger</script><script>alert('gotcha');</script>\"" +
+            "}" +
+        "}";
+
+        private readonly string jsonHtmlEscaped =
+        "{" +
+            "\"@context\":\"http://schema.org\"," +
+            "\"@type\":\"Book\"," +
+            "\"@id\":\"http://example.com/book/1\"," +
+            "\"name\":\"The Catcher in the Rye\\u003c/script\\u003e\\u003cscript\\u003ealert(\\u0027gotcha\\u0027);\\u003c/script\\u003e\"," +
+            "\"author\":{" +
+                "\"@type\":\"Person\"," +
+                "\"name\":\"J.D. Salinger\\u003c/script\\u003e\\u003cscript\\u003ealert(\\u0027gotcha\\u0027);\\u003c/script\\u003e\"" +
+            "}" +
+        "}";
+
+        private readonly JsonSerializerSettings customSerializerSettings = new JsonSerializerSettings()
+        {
+            Converters = new List<JsonConverter>()
+            {
+                new StringEnumConverter()
+            },
+            NullValueHandling = NullValueHandling.Ignore,
+            StringEscapeHandling = StringEscapeHandling.EscapeHtml,
+            Formatting = Formatting.Indented
+        };
+
+        private readonly string jsonCustom =
+        "{\r\n" +
+            "  \"@context\": \"http://schema.org\",\r\n" +
+            "  \"@type\": \"Person\",\r\n" +
+            "  \"name\": \"J.D. Salinger\\u003c/script\\u003e\\u003cscript\\u003ealert(\\u0027gotcha\\u0027);\\u003c/script\\u003e\"\r\n" +
+        "}";
+
+        [Fact]
+        public void ToString_UnsafeBookData_ReturnsExpectedJsonLd() =>
+            Assert.Equal(this.json, this.book.ToString());
+
+        [Fact]
+        public void ToHtmlEscapedString_UnsafeBookData_ReturnsExpectedJsonLd() =>
+            Assert.Equal(this.jsonHtmlEscaped, this.book.ToHtmlEscapedString());
+
+        [Fact]
+        public void ToStringWithCustomSerializerSettings_UnsafeAuthorData_ReturnsExpectedJsonLd() =>
+            Assert.Equal(this.jsonCustom, Person.ToString(this.customSerializerSettings));
+
+        [Fact]
+        public void ToStringWithNullAssignedProperty_ReturnsExpectedJsonLd()
+        {
+            var localBusiness = new LocalBusiness()
+            {
+                PriceRange = "$$$",
+                Address = null
+            };
+            var actual = localBusiness.ToString();
+            var expected =
+            "{" +
+                "\"@context\":\"http://schema.org\"," +
+                "\"@type\":\"LocalBusiness\"," +
+                "\"priceRange\":\"$$$\"" +
+            "}";
+            Assert.Equal(expected, actual);
+        }
+    }
+}