Skip to content

Commit 4b15bb8

Browse files
janderssonsejanderssonse
committed
docs: restructure concise guide and add term list
Signed-off-by: Josef Andersson <[email protected]>
1 parent 2238280 commit 4b15bb8

File tree

2 files changed

+112
-52
lines changed

2 files changed

+112
-52
lines changed

‎docs/Concise-Guide-for-Evaluating-Open-Source-Software.md

+90-52
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,95 @@
11
# Concise Guide for Evaluating Open Source Software
22

3-
_by the [Open Source Security Foundation (OpenSSF)](https://openssf.org) [Best Practices Working Group](https://best.openssf.org/), 2023-11-21_
3+
_by the [Open Source Security Foundation (OpenSSF)](https://openssf.org) [Best Practices Working Group](https://best.openssf.org/), 2025-03-28_
44

55
As a software developer, before using open source software (OSS) dependencies or tools, identify candidates and evaluate the leading ones against your needs. To evaluate a potential OSS dependency for security and sustainability, consider these questions (all tools or services listed are merely examples):
66

7-
1. **Can you avoid adding it?** Can you use an existing (possibly indirect) dependency instead? Every new dependency increases the attack surface (a subversion of the new dependency, or its transitive dependencies, may subvert the system).
8-
2. **Are you evaluating the intended version?** Ensure you are evaluating the intended version of the software, not a personal fork nor an attacker-controlled fork. These techniques help to counter the common “typosquatting” attack (where an attacker creates an “almost-correct” name).
9-
1. Check its name and the project website for the link.
10-
2. Verify the fork relation on GitHub/GitLab.
11-
3. Check if the project is affiliated with a foundation (in this case, you should be able to access the official source from the foundation’s website).
12-
4. Check its creation time, and check its popularity.
13-
3. **Is it maintained?** Unmaintained software is a risk; most software needs continuous maintenance. If it’s unmaintained, it’s also likely to be insecure.
14-
1. Has significant recent activity (e.g., commits) occurred within the last year?
15-
2. When was its last release (was it less than a year ago)?
16-
3. Is there more than one maintainer, ideally from different organizations?
17-
4. Are there recent releases or announcements from its maintainer(s)?
18-
5. Does its version string indicate instability (e.g., begin with “0”, include “alpha” or “beta”, etc.)
19-
4. **Is there evidence that its developers work to make it secure?**
20-
1. Determine whether the project has earned (or is well on the way to) an [Open Source Security Foundation (OpenSSF) Best Practices badge](https://www.bestpractices.dev/).
21-
2. Examine information on [https://deps.dev](https://deps.dev/), including its [OpenSSF Scorecards](https://github.com/ossf/scorecard) score and any known vulnerabilities.
22-
3. Determine whether the package dependencies are (relatively) up to date.
23-
4. Determine whether there is documentation explaining why it’s secure (aka an “assurance case”).
24-
5. Are there automated tests included in its CI pipeline? What is its test coverage?
25-
6. Does the project fix bugs (especially security bugs) in a timely manner? Do they release security fixes for older releases? Do they have an LTS (Long Time Support) version?
26-
7. Do the developers use code hosting security features where applicable (e.g., if they’re on GitHub or GitLab, do they use branch protection)?
27-
8. Identify security audits and whether any problems found were fixed. Security audits are relatively uncommon, but see OpenSSF’s “[Security Reviews](https://github.com/ossf/security-reviews)”.
28-
9. Use [SAFECode’s guide _Principles for Software Assurance Assessment_](https://safecode.org/resource-managing-software-security/principles-of-software-assurance-assessment/) (2019), a multi-tiered approach for examining the software’s security.
29-
10. Is the current version free of known important vulnerabilities (especially long-known ones)? Organizations may want to implement the [OpenChain](https://www.openchainproject.org/) [Security Assurance Specification 1.1](https://github.com/OpenChain-Project/Security-Assurance-Specification/tree/main/Security-Assurance-Specification/1.1/en) to systemically check for known vulnerabilities on ingest and as new vulnerabilities are publicly revealed.
30-
11. Do they apply many practices in the [Concise Guide for Developing More Secure Software](https://best.openssf.org/Concise-Guide-for-Developing-More-Secure-Software)?
31-
5. **Is it easy to use securely?**
32-
33-
1. Are the default configuration and “simple examples” secure (e.g., encryption turned on by default in network protocols)? If not, avoid it.
34-
2. Is its interface/API designed to be easy to use securely (e.g., if the interface implements a language, does it support parameterized queries)?
35-
3. Is there guidance on how to use it securely?
36-
37-
6. **Are there instructions on how to report vulnerabilities?** See the [Guide to implementing a coordinated vulnerability disclosure process for open source projects](https://github.com/ossf/oss-vulnerability-guide/blob/main/maintainer-guide.md#guide-to-implementing-a-coordinated-vulnerability-disclosure-process-for-open-source-projects) for guidance to OSS projects.
38-
7. **Does it have significant use?** Software with many users or large users may be inappropriate for your use. However, widely used software is more likely to offer useful information on how to use it securely, and more people will care about its security. Check if a similar name is more popular - that could indicate a typosquatting attack.
39-
8. **What is the software’s license?** Licenses are technically not security, but licenses can have a significant impact on security and sustainability. Ensure every component has a license, that it’s a widely-used [OSI license](https://opensource.org/licenses) if it’s OSS, and that it’s consistent with your intended use. Projects that won’t provide clear license information are less likely to follow other good practices that lead to secure software.
40-
9. **What happens on a test addition?** Try adding the dependency as a test, preferably in an isolated environment, to investigate its impact:
41-
1. Does it exhibit malicious behaviour, e.g., does it attempt to exfiltrate sensitive data?
42-
2. Does it add unexpected or unnecessary indirect dependencies in production? For example, does it include production dependencies that are only required at development time or test time instead? If so, would their maintainers be willing to fix that? Every new dependency is a potential support problem or supply chain attack, so it's wise to eliminate unnecessary ones.
43-
10. **What are the results of code evaluation?** Even a brief review of software (by you, someone you hire, or someone else), along with recent changes to it, can give you some insight. Here are things to consider:
44-
1. When reviewing its source code, is there evidence in the code that the developers were trying to develop secure software (such as rigorous input validation of untrusted input and the use of parameterized statements)?
45-
2. Is there evidence of insecure/ incomplete software (e.g., many TODO statements)?
46-
3. What are the “top” problems reported by static analysis tools?
47-
4. Is there evidence that the software is malicious? Per [_Backstabber’s Knife Collection_](https://arxiv.org/abs/2005.09535), check the installation scripts/routines for maliciousness, check for data exfiltration from **~/.ssh** and environment variables, and look for encoded/ obfuscated values that are executed. Examine the most recent commits for suspicious code (an attacker may have added them recently).
48-
5. Consider running the software in a sandbox to attempt to trigger and detect malicious code.
49-
6. Consider running all defined test cases to ensure the software passes them.
50-
7. See the [OpenSSF's list of security reviews](https://github.com/ossf/security-reviews/blob/main/Overview.md#readme).
51-
52-
Other resources you may wish to consider include:
53-
54-
1. [The Tidelift guide to choosing packages well (February 2021)](https://tidelift.com/subscription/choosing-open-source-packages-well), Tidelift
55-
2. [How to Evaluate Open Source Software / Free Software (OSS/FS) Programs](https://dwheeler.com/oss_fs_eval.html)
56-
57-
We welcome suggestions and updates! Please open an [issue](https://github.com/ossf/wg-best-practices-os-developers/issues/) or post a [pull request](https://github.com/ossf/wg-best-practices-os-developers/pulls).
7+
## Initial Assessment
8+
9+
| Rule | Description | Done |
10+
|------|-------------|:--------:|
11+
| **Consider Necessity** | Evaluate whether the dependency can be avoided by utilizing existing components. Every new dependency increases the attack surface (a subversion of the new dependency, or its transitive dependencies, may subvert the system). | |
12+
| **Verify Authenticity** | Verify that the software being evaluated is the authentic version from the authorized source, not a personal fork nor an attacker-controlled fork. These techniques help counter the common "typosquatting" attack (where an attacker creates an "almost-correct" name). Check its name and the project website for the link. Verify the fork relation on GitHub/GitLab. Check if the project is affiliated with a foundation. Check its creation time and popularity. | |
13+
14+
## Maintenance & Sustainability
15+
16+
Unmaintained software is a risk; most software needs continuous maintenance. If it's unmaintained, it's also likely to be insecure.
17+
18+
| Rule | Description | Done |
19+
|------|-------------|:--------:|
20+
| **Activity Level** | Confirm significant recent activity (e.g., commits) has occurred within the previous 12 months. | |
21+
| **Communication** | Verify the existence of recent releases or announcements from the project maintainer(s). | |
22+
| **Maintainer Diversity** | Verify the presence of more than one maintainer, ideally from different organizations, to reduce single-point-of-failure risk. | |
23+
| **Release Recency** | Confirm that the last release was issued within the previous 12 months. | |
24+
| **Version Stability** | Assess whether the version string indicates instability (e.g., begin with "0", include "alpha" or "beta", etc.). | |
25+
26+
## Security Practices
27+
28+
| Rule | Description | Done |
29+
|------|-------------|:--------:|
30+
| **Assessment Framework** | Consider using established assessment methodologies such as [SAFECode's guide _Principles for Software Assurance Assessment_](https://safecode.org/resource-managing-software-security/principles-of-software-assurance-assessment/) (2019), a multi-tiered approach for examining the software's security. | |
31+
| **Best Practices Certification** | Determine whether the project has earned (or is well on the way to) an [Open Source Security Foundation (OpenSSF) Best Practices badge](https://www.bestpractices.dev/). | |
32+
| **Dependency Management** | Verify that the package dependencies are (relatively) up to date. | |
33+
| **Repository Security** | Confirm that developers use code hosting security features where applicable (e.g., if they're on GitHub or GitLab, do they use branch protection). | |
34+
| **Security Audits** | Identify existing security audits and verify that identified vulnerabilities have been fixed. Security audits are relatively uncommon, but see OpenSSF's "[Security Reviews](https://github.com/ossf/security-reviews)". | |
35+
| **Security Development** | Confirm the project applies secure software development best practices as defined in the [Concise Guide for Developing More Secure Software](https://best.openssf.org/Concise-Guide-for-Developing-More-Secure-Software) or the [OpenSSF Open Source Security Baseline](https://baseline.openssf.org/). | |
36+
| **Security Documentation** | Verify the existence of documentation explaining why it's secure (aka an "assurance case"). | |
37+
| **Security Response** | Assess whether the project fixes bugs (especially security bugs) in a timely manner, if they release security fixes for older releases, and if they have an LTS (Long Term Support) version. | |
38+
| **Security Scores** | Examine information on [https://deps.dev](https://deps.dev/), including its [OpenSSF Scorecards](https://github.com/ossf/scorecard) score and any known vulnerabilities. | |
39+
| **Testing Practices** | Evaluate if there are automated tests included in its CI pipeline and what is its test coverage. | |
40+
| **Vulnerability Status** | Confirm if the current version is free of known important vulnerabilities (especially long-known ones). Organizations may want to implement the [OpenChain](https://www.openchainproject.org/) [Security Assurance Specification 1.1](https://github.com/OpenChain-Project/Security-Assurance-Specification/tree/main/Security-Assurance-Specification/1.1/en) to systemically check for known vulnerabilities on ingest and as new vulnerabilities are publicly revealed. | |
41+
42+
## Usability & Security
43+
44+
| Rule | Description | Done |
45+
|------|-------------|:--------:|
46+
| **Interface Design** | Verify that the interface/API is designed to be easy to use securely (e.g., if the interface implements a language, does it support parameterized queries). | |
47+
| **Interface Stability** | Verify that the interface/API is stable or that the project has a policy for avoiding and/or handling changes of interfaces/APIs which are breaking compatibility. An unstable API is a significant hindrance to uplifting to newer versions (e.g., to mitigate vulnerabilities). | |
48+
| **Secure Defaults** | Confirm that the default configuration and "simple examples" are secure (e.g., encryption turned on by default in network protocols). If not, avoid it. | |
49+
| **Security Guidance** | Verify if there is guidance on how to use it securely. | |
50+
| **Vulnerability Reporting** | Confirm if there are instructions on how to report vulnerabilities. See the [Guide to implementing a coordinated vulnerability disclosure process for open source projects](https://github.com/ossf/oss-vulnerability-guide/blob/main/maintainer-guide.md#guide-to-implementing-a-coordinated-vulnerability-disclosure-process-for-open-source-projects) for guidance to OSS projects. | |
51+
52+
## Adoption & Licensing
53+
54+
Licensing frameworks, while not directly security-related, significantly impact security and sustainability postures. Projects lacking clear licensing information frequently demonstrate deficiencies in other security best practices.
55+
56+
| Rule | Description | Done |
57+
|------|-------------|:--------:|
58+
| **License Clarity** | Verify that every component has a license, that it's a widely-used [OSI license](https://opensource.org/licenses) if it's OSS, and that it's consistent with your intended use. Projects that won't provide clear license information are less likely to follow other good practices that lead to secure software. | |
59+
| **Name Verification** | Check if a similar name is more popular - that could indicate a typosquatting attack. | |
60+
| **Usage Metrics** | Assess if it has significant use. Software with many users or large users may be inappropriate for your use. However, widely-used software is more likely to offer useful information on how to use it securely, and more people will care about its security. | |
61+
62+
## Practical Testing
63+
64+
| Rule | Description | Done |
65+
|------|-------------|:--------:|
66+
| **Behavior Testing** | Try adding the dependency as a test, preferably in an isolated environment. Does it exhibit malicious behaviour, e.g., does it attempt to exfiltrate sensitive data? | |
67+
| **Dependency Impact** | Does it add unexpected or unnecessary indirect dependencies in production? For example, does it include production dependencies that are only required at development time or test time instead? If so, would their maintainers be willing to fix that? Every new dependency is a potential support problem or supply chain attack, so it's wise to eliminate unnecessary ones. | |
68+
69+
## Code Evaluation
70+
71+
Even a brief review of software (by you, someone you hire, or someone else), along with recent changes to it, can give you some insight. Here are things to consider:
72+
73+
| Rule | Description | Done |
74+
|------|-------------|:--------:|
75+
| **Code Completeness** | Evaluate whether there is evidence of insecure/incomplete software (e.g., many TODO statements). | |
76+
| **Malicious Code Check** | Analyze if there is evidence that the software is malicious. Per [_Backstabber's Knife Collection_](https://arxiv.org/abs/2005.09535), check the installation scripts/routines for maliciousness, check for data exfiltration from **~/.ssh** and environment variables, and look for encoded/obfuscated values that are executed. Examine the most recent commits for suspicious code (an attacker may have added them recently). | |
77+
| **Sandbox Testing** | Consider running the software in a sandbox to attempt to trigger and detect malicious code. | |
78+
| **Security Implementations** | When reviewing its source code, is there evidence in the code that the developers were trying to develop secure software (such as rigorous input validation of untrusted input and the use of parameterized statements)? | |
79+
| **Security Reviews** | See the [OpenSSF's list of security reviews](https://github.com/ossf/security-reviews/blob/main/Overview.md#readme). | |
80+
| **Static Analysis** | What are the "top" problems reported by static analysis tools? | |
81+
| **Test Validation** | Consider running all defined test cases to ensure the software passes them. | |
82+
83+
## Additional Resources
84+
85+
- [The Tidelift guide to choosing packages well (February 2021)](https://tidelift.com/subscription/choosing-open-source-packages-well), Tidelift
86+
- [How to Evaluate Open Source Software / Free Software (OSS/FS) Programs](https://dwheeler.com/oss_fs_eval.html)
87+
88+
## Document Version History
89+
90+
| Date | Description |
91+
|---------|------|
92+
| 2023-11-21 | Initial document version |
93+
| 2025-04-23 | Refactor structure |
94+
95+
_We welcome suggestions and updates! Please open an [issue](https://github.com/ossf/wg-best-practices-os-developers/issues/) or post a [pull request](https://github.com/ossf/wg-best-practices-os-developers/pulls)._

0 commit comments

Comments
 (0)