* Adding missing documentation for Token-Permissions
* Make documentation for `actions` more accurate
Co-authored-by: Naveen <172697+naveensrinivasan@users.noreply.github.com>
Co-authored-by: laurentsimon <64505099+laurentsimon@users.noreply.github.com>
* Issue activity only counts if done by a maintainer
* -Using pointer so that if Github API doesn't return a value for a field, it can be nil
- Updating AuthorAssociation to use an enum
Co-authored-by: Azeem Shaikh <azeemshaikh38@gmail.com>
According to https://github.com/apps/lgtm-com
"LGTM is a code analysis platform for identifying vulnerabilities early and preventing
them from reaching production". It's used by `systemd`, `lxc` and a lot of other large
open source projects. The check is
still kind of broken in the sense that it fails to detect
projects where every PR is analyzed by LGTM before getting merged
but it's better than nothing I guess.
Co-authored-by: Naveen <172697+naveensrinivasan@users.noreply.github.com>
This commit commits the result of `make generate-docs`,
producing an updated `docs/checks.md` file, now that the
source documentation files have been changed.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Improve explanation about multiple reviewers (and their lack)
The current text oversells the value of multiple
reviewers, and falsely assumes it's always possible.
I'm a *huge* fan of having a second reviewer, but it
obviously *can't* be done when there's only 1 active participant.
Even projects with multiple active participants find it
difficult in practice if there aren't many participants.
Also, multiple reviewers guarantee nothing; the other
"reviewers" might be sock puppets or other subverted accounts.
So yes, encourage review, but let's make it clear that it
can't prevent all problems & that some projects cannot currently
do it. Put the details in Code-Review, where it best belongs.
Also, projects *can* try to remediate the lack of active participants,
so give them some practical remediation steps.
Finally: "pull request" is a GitHub-specific term. GitLab, SourceForge,
and many other forges instead use the term "merge request". So in the
interest of not locking into one specific proprietary service, let's
include a more generic term.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Make fixes based on review
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Explain how to get top score in Contributors
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Co-authored-by: Naveen <172697+naveensrinivasan@users.noreply.github.com>
* Warn when checks are prone to false negatives
Automated tools normally have some false negatives,
some false positives, or both. However, some scorecard criteria
are *especially* prone to false negatives (where a
project meets the criterion but the tool says it doesn't).
This commit adds warning text about false negatives for
criteria that are especially prone to false negatives.
In all cases the problem is that there are *many* ways to
implement the criterion, so while the tool may detect some
cases, there are countless other situations it will fail to detect.
While this doesn't *fix* the problem, warning the humans
will encourage them to double-check these criteria before
making decisions. Sometimes this is the best you can do, and
it's better than not having a warning.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Fix text per pull request feedback
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Co-authored-by: laurentsimon <64505099+laurentsimon@users.noreply.github.com>
* Improve rationale for Binary-Artifacts
I'm fine with prohibiting binary executables, but
the *rationale* for doing this was completely unclear.
This commit rewrites the rationale to explain, in hopefully
a better way, why they can be a problem.
I prefer "executable" over "binary".
On digital computers, all data (including source code) are binaries :-).
In addition, some executables are simultaneously executables
and source code, e.g., shell scripts.
So I think what is meant here is a "generated binary".
I don't really think this merits a "High" level, but that's
a different dicussion.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Tweak Binary-Artifacts rationale
Tweak Binary-Artifacts text based on comments from
@naveensrinivasan.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Co-authored-by: Naveen <172697+naveensrinivasan@users.noreply.github.com>
A lack of active maintenance isn't always an indicator of problems.
It'd be surprising if the JavaScript IsEven package got changes
every week.
Make that clearer in the check text.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Co-authored-by: Azeem Shaikh <azeemshaikh38@gmail.com>
One reason to pin dependencies is that it's one way to
counter dependency confusion attacks; mention that.
Pinning dependencies is definitely not the *only* way, and
it's not even clear it's the best way, but it's a legitimate
reason to pin dependencies in applications.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
This fixes the current misleading text about the CII
Best Practices badge. It currently says that "This badge tells us the
repo maintainers are aware of best development practices." - but
merely being "aware" doesn't earn a passing badge.
There's a long list of requirements to earn a passing badge;
we should give a sense of them here.
Note that this only checks for "passing", not silver or gold.
Note: This replaces a previous (messed-up) pull request #1009.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Modify pinned dependency docs in checks.yaml
The previous changes about pinned dependencies
modified the generated file checks.md, not the source
file checks.yaml. This commit modifies the correct
source file checks.yaml instead. It also tweaks the
text further (while we're at it).
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Check in result of make generate-docs
We've modified checks.yaml to improve the pinned
dependency discussion. This checks in the result of
`make generate-docs` so that the docs are visible
on GitHub.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Co-authored-by: Azeem Shaikh <azeemshaikh38@gmail.com>
* Tweak "pinned dependency" discussion
The Pinned-Dependency discussion has a number of problems.
First, it doesn't even define the term. Let's fix that.
Next, it *WAY* oversells what
pinned dependencies can do for you. All they do is fix the
dependency. They don't really prevent compromised dependencies;
if you pin an already-compromised dependency, you make it worse,
because now you don't automatically update to the corrected
dependency if there was a later non-malicious version.
It often slows automated security updates, so they can actually
cause a *reduction* in security (since most updates *fix*
security vulnerabilities instead of introducing a compromise).
In particular, pinned dependencies are usually a *good* idea for
applications but you should NOT pin dependencies in libraries.
If a library pins to a version, and the library is only updated
1/year, and the ecosystem requires only 1 version of a library
(true for practically all except JavaScript), users can't update any
dependencies more than 1/year (and in practice they'll never be aligned).
At least a hint of the downsides of pinning should be admitted here.
For a larger discussion, see, for example,
https://docs.google.com/document/d/1x_VrNtXCup75qA3glDd2fQOB2TakldwjKZ6pXaAjAfg/edit#
A better argument for pinning is the reproducibility it brings
when using pinning inside an application. I suggest focusing on
that first.
Pinned dependencies are still typically a good idea for applications,
but they should NOT be oversold.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Note GitHub's dependency graph
This is mentioned in the README, but those details should really
be here in the detailed documentation, not in the whole-project README.
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Minor grammar fixes
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
* Note that pinned-dependencies should only apply to apps
The scorecard project only intends to enforce pinned
dependencies on applications (not libraries), as
noted here:
https://github.com/ossf/scorecard/issues/689
However, that's not documented in docs/checks.md!
This commit makes it clear that this is *intended* to
only apply to applications. It also notes that it's not
possible for an automated tool to always categorize software
correctly (especially when a project is both).
Signed-off-by: David A. Wheeler <dwheeler@dwheeler.com>
Co-authored-by: laurentsimon <64505099+laurentsimon@users.noreply.github.com>
The minisign project uses *.minisig signature files, which
is correctly searched for by the implementation logic
in signed_releases.go, however, the docs use
"*.minisign", which will confuse users.
Correct the docs to use the "*.minisig" file extension.
Co-authored-by: Naveen <172697+naveensrinivasan@users.noreply.github.com>
