> ## Documentation Index
> Fetch the complete documentation index at: https://cloudanix.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Outside collaborators mfa required remediation

### Triage and Remediation

<Tabs>
  <Tab title="Remediation">
    ### Remediation

    <AccordionGroup>
      <Accordion title="Using Console" defaultOpen="true">
        Below are the steps to remediate an “Outside Collaborator MFA required” issue in GitHub using the web console.

        ### 1. Enable 2FA requirement for the GitHub Organization

        1. Sign in to GitHub with an organization owner account.
        2. In the top‑right corner, click your profile picture → **Your organizations**.
        3. Click the organization that has the issue.
        4. In the organization sidebar, go to **Settings**.
        5. In the left menu, click **Security** (or **Authentication security**, depending on UI layout).
        6. Under **Two‑factor authentication**, check **Require two-factor authentication for everyone in the organization** (wording may be “Require 2FA for all members, outside collaborators, and billing managers”).
        7. Read the warning (GitHub will remove members/collaborators without 2FA after a grace period).
        8. Click **Save** / **Enable** and confirm.

        This enforces MFA for:

        * Organization members
        * Outside collaborators
        * Billing managers

        ### 2. Identify outside collaborators without 2FA

        1. Go to the organization’s main page.
        2. Click **People** in the top menu.
        3. Click the **Outside collaborators** tab.
        4. Look for a 2FA status column (or filter, if present):
           * Some UIs show a shield icon or “2FA” column.
           * If available, filter or sort to see who doesn’t have 2FA enabled.

        If a direct 2FA filter is not visible, you can:

        * Go to **Settings → Security → Authentication security**.
        * Look for the list or export options that show who does not have 2FA enabled.

        ### 3. Remove or restrict non‑compliant outside collaborators (if needed)

        If policy requires immediate compliance and some outside collaborators still don’t have MFA enabled:

        1. In **People → Outside collaborators**, click the name of the collaborator.
        2. Click **Remove from all repositories** or remove them from individual repos as required.
        3. Optionally, document or notify them that they must:
           * Enable 2FA in **Settings → Password and authentication → Two-factor authentication**, then
           * Be re‑added as outside collaborators.

        ### 4. Instruct outside collaborators to enable their own 2FA

        Provide them with this short path:

        1. User clicks their profile picture → **Settings**.
        2. In the left menu, click **Password and authentication**.
        3. Under **Two-factor authentication**, click **Enable two-factor authentication**.
        4. Choose an authentication method (TOTP app or security key) and complete setup.
        5. Save recovery codes.

        Once they have 2FA enabled, they can be safely added (or re‑added) as outside collaborators while remaining compliant with the “MFA required” control.
      </Accordion>

      <Accordion title="Using CLI">
        Below are step‑by‑step instructions to require MFA for outside collaborators in a GitHub organization using the GitHub CLI (`gh`).

        > Important: GitHub enforces 2FA **at the organization level**. When you require 2FA for the org, it applies to **members, billing managers, and outside collaborators**. Anyone (including outside collaborators) without 2FA will be removed from the org after a grace period.

        ***

        ## 1. Prerequisites

        1. Install / update GitHub CLI:
           ```bash theme={null}
           gh --version
           ```
           If not installed: [https://cli.github.com/](https://cli.github.com/)

        2. Authenticate with an account that:

           * Is an **organization owner**, and
           * Has a token scope including: `admin:org`.

           ```bash theme={null}
           gh auth login
           ```

        3. Set an environment variable for your org (optional but convenient):
           ```bash theme={null}
           ORG_NAME="your-org-name"
           ```

        ***

        ## 2. Check Current 2FA Requirement Setting

        ```bash theme={null}
        gh api \
          -H "Accept: application/vnd.github+json" \
          /orgs/$ORG_NAME \
          --jq '.login, .two_factor_requirement_enabled'
        ```

        * `two_factor_requirement_enabled == true` → 2FA already required.
        * `false` → continue to next step.

        ***

        ## 3. (Optional) See Who Is Missing 2FA

        ### 3.1. Organization members without 2FA

        ```bash theme={null}
        gh api \
          -H "Accept: application/vnd.github+json" \
          "/orgs/$ORG_NAME/members?filter=2fa_disabled&per_page=100" \
          --paginate \
          --jq '.[].login'
        ```

        ### 3.2. Outside collaborators without 2FA

        Many orgs can also filter outside collaborators by 2FA status:

        ```bash theme={null}
        gh api \
          -H "Accept: application/vnd.github+json" \
          "/orgs/$ORG_NAME/outside_collaborators?filter=2fa_disabled&per_page=100" \
          --paginate \
          --jq '.[].login'
        ```

        If the `filter` query parameter is not supported on your plan, list all collaborators then check them manually:

        ```bash theme={null}
        gh api \
          -H "Accept: application/vnd.github+json" \
          "/orgs/$ORG_NAME/outside_collaborators?per_page=100" \
          --paginate \
          --jq '.[].login'
        ```

        ***

        ## 4. Enable “Require 2FA” for the Organization (Affects Outside Collaborators Too)

        ```bash theme={null}
        gh api \
          --method PATCH \
          -H "Accept: application/vnd.github+json" \
          /orgs/$ORG_NAME \
          -f two_factor_requirement_enabled=true
        ```

        Verify:

        ```bash theme={null}
        gh api \
          -H "Accept: application/vnd.github+json" \
          /orgs/$ORG_NAME \
          --jq '.two_factor_requirement_enabled'
        ```

        Should return `true`.

        > Outcome: All outside collaborators must enable 2FA. GitHub will:
        >
        > * Notify users without 2FA.
        > * After the grace period, remove them from the org if they still don’t have 2FA.

        ***

        ## 5. (Optional) Proactively Remove Non‑2FA Outside Collaborators

        If you want to immediately remove outside collaborators that do not have 2FA, you can script it.

        List them:

        ```bash theme={null}
        gh api \
          -H "Accept: application/vnd.github+json" \
          "/orgs/$ORG_NAME/outside_collaborators?filter=2fa_disabled&per_page=100" \
          --paginate \
          --jq '.[].login'
        ```

        Then, for each username (example with a loop):

        ```bash theme={null}
        for user in $(gh api \
          -H "Accept: application/vnd.github+json" \
          "/orgs/$ORG_NAME/outside_collaborators?filter=2fa_disabled&per_page=100" \
          --paginate \
          --jq '.[].login'); do

          echo "Removing outside collaborator: $user"
          gh api \
            --method DELETE \
            -H "Accept: application/vnd.github+json" \
            "/orgs/$ORG_NAME/outside_collaborators/$user"
        done
        ```

        ***

        If you tell me your org name and whether you want to auto-remove non‑MFA collaborators immediately or just enforce at org level, I can tailor a ready-to-run script.
      </Accordion>

      <Accordion title="Using Python">
        For GitHub, “requiring MFA for outside collaborators” is not directly configurable via an API flag the way org-wide 2FA is. The practical, automatable remediation is:

        * Enforce org-wide 2FA for members.
        * Detect outside collaborators.
        * Remove (or quarantine) outside collaborators that do not meet your MFA requirement policy (e.g., by process, or by converting them to org members and enforcing 2FA).

        Below is how to remediate with Python using the GitHub API (via PyGithub) in a typical pattern used by security teams.

        ***

        ## 1. Prerequisites

        1. **Personal Access Token (classic)** (or a GitHub App) with scopes:
           * `admin:org` (to list and remove outside collaborators)
           * `read:org`
        2. **Organization name** where you want to manage outside collaborators.
        3. Python 3.8+ and `PyGithub`:

        ```bash theme={null}
        pip install PyGithub
        ```

        ***

        ## 2. Enforce org-wide 2FA for members (UI step)

        This is not currently configurable via REST API; set it once in the UI:

        1. Go to: `https://github.com/organizations/<ORG_NAME>/settings/security`
        2. Under **Two-factor authentication**, enable **Require two-factor authentication for everyone in your organization**.

        This **does not** apply to outside collaborators, only org members. For outside collaborators you must act via policy and automation.

        ***

        ## 3. List outside collaborators with Python

        This script lists all outside collaborators for an org:

        ```python theme={null}
        from github import Github
        import os

        # Set these
        GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")  # or hard-code for testing
        ORG_NAME = "your-org-name"

        g = Github(GITHUB_TOKEN)
        org = g.get_organization(ORG_NAME)

        outside_collaborators = list(org.get_outside_collaborators())
        print(f"Found {len(outside_collaborators)} outside collaborators:")
        for user in outside_collaborators:
            print(user.login)
        ```

        Run:

        ```bash theme={null}
        export GITHUB_TOKEN=<your_token>
        python list_outside_collaborators.py
        ```

        ***

        ## 4. Automated remediation pattern

        Because 2FA status for outside collaborators is not exposed via API, common remediation strategies are:

        1. **Policy:** “No outside collaborators; all contributors must be org members with 2FA.”
        2. Then:
           * Convert valid collaborators to org members (they will be forced to enable 2FA by your org-wide setting).
           * Remove all remaining outside collaborators via script.

        ### 4.1. Convert an outside collaborator to an org member (then 2FA is enforced)

        You need to *invite* them as an org member:

        ```python theme={null}
        from github import Github
        import os

        GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
        ORG_NAME = "your-org-name"

        g = Github(GITHUB_TOKEN)
        org = g.get_organization(ORG_NAME)

        # Example: promote one user
        username_to_promote = "outside-collab-username"

        user = g.get_user(username_to_promote)
        # role="direct_member" or "admin" or "billing_manager"
        invitation = org.invite_user(user=user, role="direct_member")
        print(f"Invited {username_to_promote} as org member; once accepted, org 2FA policy will apply.")
        ```

        You can apply this to each approved outside collaborator (for whom your internal checks say “ok to keep”).

        ***

        ## 5. Remove outside collaborators (strict remediation)

        If your security policy is “no outside collaborators at all” (commonly used to effectively require 2FA by forcing membership), use:

        ```python theme={null}
        from github import Github
        import os

        GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
        ORG_NAME = "your-org-name"

        g = Github(GITHUB_TOKEN)
        org = g.get_organization(ORG_NAME)

        outside_collaborators = list(org.get_outside_collaborators())

        print(f"Removing {len(outside_collaborators)} outside collaborators...")
        for user in outside_collaborators:
            print(f"Removing {user.login} as outside collaborator")
            org.remove_outside_collaborator(user)
        ```

        This removes their access to **all** org repositories where they are outside collaborators.

        ***

        ## 6. Recommended end state

        To effectively “require MFA for outside collaborators” in GitHub IAM using automation:

        1. **Enable org-wide 2FA for members** (UI).
        2. **Run a Python job (CI or scheduled)** that:
           * Lists all outside collaborators.
           * For any *approved* collaborators, invites them as members (enforces 2FA).
           * For any *unapproved* collaborators, removes them as outside collaborators.
        3. Optionally log or notify (Slack/email) before removal so repo owners can review.

        If you share your exact policy (“remove all outside collaborators” vs. “only some”), I can provide a ready-to-run Python script tailored to that policy (with dry-run, logging, and optional Slack/email notifications).
      </Accordion>

      <Accordion title="Using Terraform">
        ```hcl theme={null}
        # Terraform cannot currently manage the GitHub organization setting
        # that requires 2FA/MFA for outside collaborators.
        #
        # The integrations/github provider does not expose an argument for the
        # "Require two-factor authentication for outside collaborators" control
        # on any resource (including github_organization_settings), so this
        # finding cannot be remediated via Terraform.

        # You must set this in the GitHub UI:
        # 1. In GitHub, go to: Settings > Organizations > YOUR_ORG_NAME.
        # 2. Under "Security" or "Authentication security", locate
        #    "Require two-factor authentication for outside collaborators".
        # 3. Enable it and save.
        ```

        For verification, `terraform plan` will show no changes related to MFA/2FA for outside collaborators, because the provider does not expose that setting.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>