Skip to content

Latest commit

 

History

History
124 lines (93 loc) · 7.27 KB

mitigations.md

File metadata and controls

124 lines (93 loc) · 7.27 KB

Mitigation Strategies Analysis for realm/jazzy

Mitigation Strategy: Rigorous Use of Access Control Modifiers (with Jazzy in mind)

Description:

  1. Review Codebase: Systematically examine all Swift and Objective-C code.
  2. Identify Public API: Determine which elements are intended for the public API.
  3. Apply public or open: Mark only the intended public API with public or open.
  4. Apply internal: Use internal for elements within the same module.
  5. Apply fileprivate: Use fileprivate for elements within the same source file.
  6. Apply private: Use private for elements within the enclosing declaration.
  7. Consistency Check: Regularly review to ensure consistent and correct usage.
  8. Jazzy Consideration: Keep in mind that jazzy will, by default, document public, open, and internal elements. Use private and fileprivate to prevent documentation generation.

  • List of Threats Mitigated:

    • Exposure of Internal APIs (Severity: High): Prevents internal details from being included in the generated documentation.
    • Accidental Public Exposure (Severity: Medium): Reduces the risk of unintentionally making internal components public.
    • Information Leakage (Severity: Medium): Limits the amount of information about internal structure.

  • Impact:

    • Exposure of Internal APIs: Significantly reduces the risk (primary defense).
    • Accidental Public Exposure: Significantly reduces the risk.
    • Information Leakage: Significantly reduces the risk.

  • Currently Implemented:

    • *Example: "Partially implemented. Access control modifiers are used in CoreData and Networking, but inconsistently in UI and Utilities."

  • Missing Implementation:

    • *Example: "Missing in LegacyCode and helper classes in Utilities. StringExtensions.swift and DateHelpers.swift lack consistent access control."

Mitigation Strategy: Use of --min-acl Flag

Description:

  1. Identify Minimum Access Level: Determine the minimum access level for documentation (usually public for libraries, internal for some apps).
  2. Modify jazzy Command: Add --min-acl followed by the access level (e.g., jazzy --min-acl public).
  3. Integrate into Build Process: Ensure this command is used consistently (build script or CI/CD).
  4. Test: Run jazzy and verify the documentation includes only elements with the specified level or higher.

  • List of Threats Mitigated:

    • Exposure of Internal APIs (Severity: High): "Fail-safe" to prevent internal APIs from being included.
    • Accidental Public Exposure (Severity: Medium): Reinforces the intended public API.
    • Inconsistent Access Control (Severity: Medium): Mitigates inconsistent access control modifier use.

  • Impact:

    • Exposure of Internal APIs: Significantly reduces risk (backup to access control).
    • Accidental Public Exposure: Significantly reduces risk.
    • Inconsistent Access Control: Moderately reduces risk.

  • Currently Implemented:

    • *Example: "Implemented in generate_docs.sh, run as part of CI/CD."

  • Missing Implementation:

    • *Example: "Not used in local development builds. Developers need to be reminded to use the flag."

Mitigation Strategy: Use of --exclude Flag

Description:

  1. Identify Files/Directories to Exclude: Determine files/directories to never include (e.g., internal helpers, tests).
  2. Modify jazzy Command: Add --exclude followed by a comma-separated list of files/directories (e.g., jazzy --exclude Source/Internal/*,Tests/*).
  3. Integrate into Build Process: Ensure consistent use (build script or CI/CD).
  4. Test: Run jazzy and verify excluded files/directories are not in the documentation.

  • List of Threats Mitigated:

    • Exposure of Internal APIs (Severity: High): Excludes entire code sections, regardless of access control.
    • Exposure of Sensitive Code (Severity: High): Excludes files with sensitive details.
    • Inclusion of Irrelevant Code (Severity: Low): Prevents test files, etc., from cluttering documentation.

  • Impact:

    • Exposure of Internal APIs: Significantly reduces risk for excluded files/directories.
    • Exposure of Sensitive Code: Significantly reduces risk for excluded files/directories.
    • Inclusion of Irrelevant Code: Eliminates risk for excluded files/directories.

  • Currently Implemented:

    • *Example: "Implemented in generate_docs.sh. Excludes Tests and files matching *Internal.swift."

  • Missing Implementation:

    • *Example: "Not used to exclude specific files in Utilities, even though some helper classes should be excluded."

Mitigation Strategy: Use of //:nodoc: Comment Tag

Description:

  1. Identify Elements to Exclude: Identify specific code elements to exclude, even if public or internal.
  2. Add //:nodoc: Tag: Before the element, add //:nodoc: (e.g., //:nodoc: public func helper() { ... }).
  3. Test: Run jazzy and verify marked elements are excluded.

  • List of Threats Mitigated:

    • Exposure of Specific Internal Elements (Severity: Medium): Fine-grained control over included elements.
    • Temporary Exclusion (Severity: Low): Temporarily hide parts of the API.

  • Impact:

    • Exposure of Specific Internal Elements: Significantly reduces risk for marked elements.
    • Temporary Exclusion: Convenient for temporary hiding.

  • Currently Implemented:

    • *Example: "Used sporadically, primarily in Networking to exclude internal helpers."

  • Missing Implementation:

    • *Example: "Not consistently used. Many internal helpers within public classes are not marked."

Mitigation Strategy: Keep jazzy Updated

Description:

  1. Check for Updates: Regularly check for new jazzy (and SourceKitten) versions:
    • jazzy GitHub repository
    • SourceKitten GitHub repository
    • Dependency manager
  2. Update Dependencies: Update to new versions, following instructions.
  3. Test: Run jazzy and verify correct documentation generation, no regressions.

  • List of Threats Mitigated:

    • Vulnerabilities in jazzy (Severity: Low to High): Updates often include security patches.
    • Vulnerabilities in SourceKitten (Severity: Low to High): Updating jazzy often updates SourceKitten.
    • Bugs and Compatibility Issues (Severity: Low): Updates fix bugs, improve compatibility.

  • Impact:

    • Vulnerabilities in jazzy and SourceKitten: Reduces risk (potentially significantly).
    • Bugs and Compatibility Issues: Improves stability and reliability.

  • Currently Implemented:

    • *Example: "Dependencies managed through Swift Package Manager, updates checked weekly."

  • Missing Implementation:

    • *Example: "No automated update checks. Relies on manual checks."