mitigations.md

Mitigation Strategies Analysis for dotnet/docfx

Mitigation Strategy: Strict Source Code Filtering with DocFX

1. Mitigation Strategy: Strict Source Code Filtering with DocFX

• Description:

  1. .docfxignore Files: Create and maintain .docfxignore files in the root directory and, if necessary, subdirectories of your project. These files use a syntax similar to .gitignore. Add entries to exclude:
     • Entire directories containing internal-only projects or test code (e.g., **/InternalProjects/, **/Tests/).
     • Specific files known to contain sensitive data (e.g., **/SensitiveConfig.cs).
     • Patterns matching files that should be excluded (e.g., **/*Internal*.cs).
  2. docfx.json Configuration:
     • filterConfig: Use the filterConfig section to define precise inclusion/exclusion rules.
       • apiRules: Define rules based on member visibility. For example:

         "filterConfig": {
           "apiRules": [
             {
               "include": {
                 "kind": "class",
                 "visibility": "public"
               }
             },
             {
               "include": {
                 "kind": "method",
                 "visibility": "public"
               }
             },
             { "exclude": { "uid": ".*Internal.*" } } // Exclude anything with "Internal" in the UID
           ]
         }

       • namespace and type: Specify explicit namespaces and types to include or exclude.
     • metadata: Carefully review the metadata section to ensure it doesn't contain any sensitive information.
  3. Regular DocFX Output Audits: After each DocFX build, manually inspect a representative sample of the generated output. Look for:
     • Unexpectedly exposed internal classes or methods.
     • Sensitive comments or documentation strings.
     • Any other information that should not be public.
     • Consider scripting this audit to search for specific keywords or patterns.

• Threats Mitigated:

  • Exposure of Internal/Sensitive Information: (Severity: High) - Prevents internal APIs, private methods, sensitive comments, and configuration details from being exposed in the public documentation.
  • Accidental Disclosure of Credentials: (Severity: Critical) - Reduces the risk (though doesn't eliminate it entirely – source code control is still key) of API keys or other credentials being exposed if they were accidentally included in the source code and not caught by code reviews.

• Impact:

  • Exposure of Internal/Sensitive Information: Risk significantly reduced. The combination of .docfxignore and filterConfig provides strong control over what DocFX processes.
  • Accidental Disclosure of Credentials: Risk reduced, but relies on other mitigations (code reviews, environment variables) for complete protection.

• Currently Implemented:

  • .docfxignore Files: Partially implemented. A basic .docfxignore exists, but it may not be comprehensive.
  • docfx.json Configuration: Partially implemented. filterConfig is used, but may not be fully optimized.
  • Regular DocFX Output Audits: Not implemented.

• Missing Implementation:

  • .docfxignore Files: Need to conduct a thorough review of the project structure and create/update .docfxignore files to exclude all internal-only code and sensitive files.
  • docfx.json Configuration: Need to refine the filterConfig to be more precise and restrictive, especially the apiRules.
  • Regular DocFX Output Audits: Need to establish a schedule and process (potentially automated) for regular audits of the generated documentation.

Mitigation Strategy: Secure Custom Template Handling within DocFX

2. Mitigation Strategy: Secure Custom Template Handling within DocFX

• Description:

  1. Handlebars Template Sanitization (Triple Braces): Within custom Handlebars templates used by DocFX, always use triple curly braces ({{{ ... }}}) to output any data that originates from:
     • Source code comments.
     • User-provided input (if any – this should be rare in DocFX contexts).
     • Any source that is not 100% guaranteed to be safe HTML.
     • This prevents Handlebars from performing HTML escaping, which is crucial for preventing XSS.
  2. Handlebars Template Sanitization (Double Braces - with extreme caution): If you absolutely must use double curly braces ({{ ... }}), ensure the data being output is:
     • Completely trusted (e.g., a hardcoded string within the template itself).
     • Or, has been thoroughly sanitized using a dedicated HTML sanitization library before being passed to the template. This is a complex and error-prone approach; triple braces are strongly preferred.
  3. Avoid Custom Helpers: Minimize the use of custom Handlebars helpers. If you must create custom helpers:
     • Rigorously review their code for any potential XSS vulnerabilities.
     • Ensure they properly sanitize any input they receive before incorporating it into the output.
  4. Review Existing Templates: Conduct a thorough security review of all existing custom Handlebars templates.
     • Check for any instances of double curly braces being used with untrusted data.
     • Verify that any custom helpers are secure.

• Threats Mitigated:

  • Cross-Site Scripting (XSS) in Custom Templates: (Severity: High) - Prevents attackers from injecting malicious JavaScript into the generated documentation via vulnerabilities in custom Handlebars templates.

• Impact:

  • Cross-Site Scripting (XSS) in Custom Templates: Risk significantly reduced. Consistent use of triple curly braces for untrusted data, combined with careful review of existing templates, provides strong protection against XSS.

• Currently Implemented:

  • Handlebars Template Sanitization: Partially implemented. Developers are aware of triple curly braces, but usage may not be consistent or fully understood.
  • Avoid Custom Helpers: Mostly implemented (few custom helpers are used).
  • Review Existing Templates: Not implemented.

• Missing Implementation:

  • Handlebars Template Sanitization: Need to conduct a code review of all custom Handlebars templates to ensure consistent and correct use of triple curly braces. Provide training to developers on the importance of this.
  • Review Existing Templates: Need to perform a dedicated security review of all existing custom templates.

Mitigation Strategy: DocFX Build Process Optimization

3. Mitigation Strategy: DocFX Build Process Optimization

• Description:

  1. Incremental Builds: Always enable incremental builds. This is typically done by:
     • Adding the --incremental flag to the docfx build command.
     • Or, configuring it within the build section of your docfx.json file:

       "build": {
         "incremental": true
       }

  2. xrefService Optimization (if used): If your project uses cross-references to external documentation via the xrefService, carefully configure it in docfx.json.
     • Avoid overly broad or unnecessary xref mappings.
     • Specify only the required external documentation sources.
     • Consider using a local xref map file if the external documentation is static.
  3. Plugin Minimization:
     • Only include DocFX plugins that are absolutely essential for your documentation needs.
     • Each plugin adds overhead to the build process.
     • Regularly review the list of installed plugins and remove any that are no longer used.

• Threats Mitigated:

  • Denial of Service (DoS) via Resource Exhaustion During Build: (Severity: Medium) - Prevents the DocFX build process from consuming excessive resources (CPU, memory) on the build server, which could lead to a denial-of-service condition.

• Impact:

  • Denial of Service (DoS) via Resource Exhaustion During Build: Risk significantly reduced. Incremental builds, optimized xrefService configuration, and plugin minimization all contribute to a more efficient build process.

• Currently Implemented:

  • Incremental Builds: Implemented.
  • xrefService Optimization: Partially implemented (needs review).
  • Plugin Minimization: Partially implemented (informal practice, needs formal review).

• Missing Implementation:

  • xrefService Optimization: Need to thoroughly review the xrefService configuration in docfx.json to ensure it's as efficient as possible.
  • Plugin Minimization: Need to conduct a formal review of all installed DocFX plugins and remove any that are not strictly necessary.