After you've submitted your app for approval, the GitHub security team will request that you complete a security questionnaire about your app and overall security program. As part of the review, you will have the option to provide documentation to support your responses. You must submit two required documents before your app will be approved for GitHub Marketplace: an incident response plan and vulnerability management workflow.
Follow these best practices to have a successful security review and provide a secure user experience.
We recommend submitting a GitHub App rather than an OAuth App. GitHub Apps are the officially recommended way to integrate with GitHub because they offer much more granular permissions to access data. See "Differences between GitHub Apps and OAuth Apps" for more details.
- Apps must use the "principle of least privilege" and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality.
- Apps must provide customers with a way to delete their account, without having to email or call a support person.
- Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately.
- Design your app with different user roles, depending on the functionality needed by each type of user. For example, a standard user should not have access to admin functionality, and billing managers might not need push access to repository code.
- Your app should not share service accounts such as email or database services to manage your SaaS service.
- All services used in your app should have unique login and password credentials.
- Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties.
- Apps cannot use personal access tokens to authenticate and must authenticate as an OAuth App or GitHub App:
- Apps must encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git.
- Apps must store client ID and client secret keys securely. We recommend storing them as environmental variables.
- Apps must delete all GitHub user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with GitHub.
- Apps cannot require the user to provide their GitHub password.
- Apps should encrypt tokens, client IDs, and client secrets.
- Apps must have logging and monitoring capabilities. App logs must be retained for at least 30 days and archived for at least one year.
A security log should include:
- Authentication and authorization events
- Service configuration changes
- Object reads and writes
- All user and group permission changes
- Elevation of role to admin
- Consistent timestamping for each event
- Source users, IP addresses, and/or hostnames for all logged actions
- To partner with GitHub, you are required to have an incident response plan in place before submitting your GitHub Marketplace app listing.
- We recommend having a security and operations incident response team in your company rather than using a third-party vendor.
- You should have the capability to notify GitHub within 24 hours of a confirmed incident.
- You should familiarize yourself with sections 3.7.5 - 22.214.171.124 of the GitHub Marketplace Developer Agreement, which include additional details on incident response workflow requirements.
- You should conduct regular vulnerability scans of production infrastructure.
- You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability.
- You should familiarize yourself with section 3.7.3 of the GitHub Marketplace Developer Agreement, which includes additional details on vulnerability management and patching workflows requirements.
During the Marketplace security review, you will be asked to submit your incident response plan and vulnerability management workflow. Each document must include a company-branded statement signed by management with a date stamp.
Your incident response plan documentation must include the current process that your company follows, who is accountable, and the person to contact or expect contact from if an incident occurs. The "NIST Computer Security Incident Handling Guide" is a great example of a document that covers incident response in general. Section 2.3 "Incident Response Policy, Plan, and Procedure Creation" specifically covers the policy. Another great example is the "SANS Data Breach Response Policy."
Your vulnerability management workflow documentation must include the current process that your company follows for vulnerability management and the patching process used. If you don't have a full vulnerability management program, it might help to start by creating a patching process. For guidance in creating a patch management policy, read the article "Establish a patch management policy."
Note: The incident response and vulnerability management workflow documents aren't expected to be massive formal policy or program documents. A page or two about what you do is more valuable than a lengthy policy template.
During the app submission process, our GitHub Marketplace onboarding team will also send you a questionnaire requesting information about your security practices. This document will serve as a written record attesting:
- The authentication method and scopes required by your app.
- That you're not requesting more scopes or GitHub access than is needed for the app to perform its intended functionality, taking OAuth limitations and use of GitHub Apps into account.
- The use of any third-party services or infrastructure, such as SaaS, PaaS, or IaaS.
- An incident response procedure exists.
- Your app's method of key/token handling.
- That a responsible disclosure policy and process in place or plans to implement one within six months.
- Your vulnerability management workflow or program.
- That you have logging and monitoring capabilities. You must also provide evidence that any relevant app logs are retained for at least 30 days and archived for at least one year.