GHA: detect "bad" words in documentation

.github/scripts/badwords.ok

@@ -0,0 +1,4 @@
+# whitelisted uses of bad words
+# file:line:rule
+docs/CVE-2020-19909.md:32:\bwill\b
+docs/CVE-2023-38546.md:36:file name\b

.github/scripts/badwords.pl

@@ -0,0 +1,94 @@
+#!/usr/bin/perl
+# Copyright (C) Daniel Stenberg, <[email protected]>, et al.
+#
+# SPDX-License-Identifier: curl
+#
+# bad[:=]correct
+#
+# If separator is '=', the string will be compared case sensitively.
+# If separator is ':', the check is done case insensitively.
+#
+
+my %wl;
+if($ARGV[0] eq "-w") {
+    shift @ARGV;
+    my $file = shift @ARGV;
+    open(W, "<$file");
+    while(<W>) {
+        if(/^#/) {
+            # allow #-comments
+            next;
+        }
+        if(/^([^:]*):(\d+):(.*)/) {
+            $wl{"$1:$2:$3"}=1;
+            #print STDERR "whitelisted $1:$2:$3\n";
+        }
+    }
+    close(W);
+}
+
+my $w;
+while(<STDIN>) {
+    chomp;
+    if($_ =~ /^#/) {
+        next;
+    }
+    if($_ =~ /^([^:=]*)([:=])(.*)/) {
+        my ($bad, $sep, $better)=($1, $2, $3);
+        push @w, $bad;
+        $alt{$bad} = $better;
+        if($sep eq "=") {
+            $exactcase{$bad} = 1;
+        }
+    }
+}
+
+my $errors;
+
+sub file {
+    my ($f) = @_;
+    my $l = 0;
+    open(F, "<$f");
+    while(<F>) {
+        my $in = $_;
+        $l++;
+        chomp $in;
+        if($in =~ /^    /) {
+            next;
+        }
+        # remove the link part
+        $in =~ s/(\[.*\])\(.*\)/$1/g;
+        # remove backticked texts
+        $in =~ s/\`.*\`//g;
+        foreach my $w (@w) {
+            my $case = $exactcase{$w};
+            if(($in =~ /^(.*)$w/i && !$case) ||
+               ($in =~ /^(.*)$w/ && $case) ) {
+                my $p = $1;
+                my $c = length($p)+1;
+
+                my $ch = "$f:$l:$w";
+                if($wl{$ch}) {
+                    # whitelisted
+                    print STDERR "$ch found but whitelisted\n";
+                    next;
+                }
+
+                print STDERR  "$f:$l:$c: error: found bad word \"$w\"\n";
+                printf STDERR " %4d | $in\n", $l;
+                printf STDERR "      | %*s^%s\n", length($p), " ",
+                    "~" x (length($w)-1);
+                printf STDERR " maybe use \"%s\" instead?\n", $alt{$w};
+                $errors++;
+            }
+        }
+    }
+    close(F);
+}
+
+my @files = @ARGV;
+
+foreach my $each (@files) {
+    file($each);
+}
+exit $errors;

.github/scripts/badwords.txt

@@ -0,0 +1,50 @@
+# Copyright (C) Daniel Stenberg, <[email protected]>, et al.
+#
+# SPDX-License-Identifier: curl
+#
+back-end:backend
+e-mail:email
+run-time:runtime
+set-up:setup
+tool chain:toolchain
+tool-chain:toolchain
+wild-card:wildcard
+wild card:wildcard
+i'm:I am
+you've:You have
+they've:They have
+they're:They are
+should've:should have
+don't:do not
+could've:could have
+doesn't:does not
+isn't:is not
+ a html: an html
+ a http: an http
+ a ftp: an ftp
+ url =URL
+internet\b=Internet
+isation:ization
+it's:it is
+there's:there is
+[^.]\. And: Rewrite it somehow?
+^(And|So|But) = Rewrite it somehow?
+\. But: Rewrite it somehow?
+\. So : Rewrite without "so" ?
+ dir :directory
+you'd:you would
+you'll:you will
+can't:cannot
+that's:that is
+web page:webpage
+host name\b:hostname
+host names\b:hostnames
+file name\b:filename
+file names\b:filenames
+\buser name\b:username
+\buser names\b:usernames
+didn't:did not
+doesn't:does not
+won't:will not
+couldn't:could not
+\bwill\b:rewrite to present tense

.github/workflows/badwords.yml

@@ -0,0 +1,29 @@
+# Copyright (C) Daniel Stenberg, <[email protected]>, et al.
+#
+# SPDX-License-Identifier: curl
+
+name: badwords
+
+on:
+  # Trigger the workflow on push or pull requests, but only for the
+  # master branch
+  push:
+    branches:
+    - master
+    - '*/ci'
+  pull_request:
+    branches:
+    - master
+
+permissions: {}
+
+jobs:
+  check:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4
+
+    - name: check
+      run: ./.github/scripts/badwords.pl -w ./.github/scripts/badwords.ok < .github/scripts/badwords.txt docs/*.md

docs/CVE-2005-0490.md

@@ -25,7 +25,7 @@ CWE-121: Stack-based Buffer Overflow
 Severity: High
 
 (This flaw was originally treated as two separate ones by the curl project,
-but due to it using a single CVE number we've reconsidered.)
+but due to it using a single CVE number we have reconsidered.)
 
 AFFECTED VERSIONS
 -----------------

docs/CVE-2005-3185.md

@@ -8,14 +8,14 @@ VULNERABILITY
 -------------
 
 libcurl's NTLM function can overflow a stack-based buffer if given a too long
-user name or domain name. This would happen if you enable NTLM authentication
+username or domain name. This would happen if you enable NTLM authentication
 and either:
 
- A - pass in a user name and domain name to libcurl that together are longer
+ A - pass in a username and domain name to libcurl that together are longer
      than 192 bytes
 
  B - allow (lib)curl to follow HTTP "redirects" (Location: and the appropriate
-     HTTP 30x response code) and the new URL contains a URL with a user name
+     HTTP 30x response code) and the new URL contains a URL with a username
      and domain name that together are longer than 192 bytes
 
 INFO

docs/CVE-2006-1061.md

@@ -63,7 +63,7 @@ TIMELINE
 We were notified March 10, 2006. The notification email contained a valid
 patch.
 
-Daniel didn't read the mail until the 12th due to vacations.
+Daniel did not read the mail until the 12th due to vacations.
 
 curl 7.15.3 was released on March 20 2006, just before this flaw was
 publicly disclosed.

docs/CVE-2007-3564.md

@@ -8,8 +8,8 @@ VULNERABILITY
 -------------
 
 libcurl (when built to use GnuTLS) fails to verify that a peer's certificate
-hasn't already expired or hasn't yet become valid. This allows malicious
-servers to present certificates to libcurl that won't be rejected properly.
+has not already expired or has not yet become valid. This allows malicious
+servers to present certificates to libcurl that were not rejected properly.
 
 Notably, the CA certificate and common name checks are still in place which
 reduces the risk for random servers to take advantage of this flaw.

docs/CVE-2009-0037.md

@@ -7,10 +7,10 @@ Project curl Security Advisory, March 3rd 2009
 VULNERABILITY
 -------------
 
-When told to follow a "redirect" automatically, libcurl does not question
-the new target URL but will follow to any new URL that it understands. As
-libcurl supports FILE:// URLs, a rogue server can thus "trick" a
-libcurl-using application to read a local file instead of the remote one.
+When told to follow a "redirect" automatically, libcurl does not question the
+new target URL but follows it to any new URL that it understands. As libcurl
+supports FILE:// URLs, a rogue server can thus "trick" a libcurl-using
+application to read a local file instead of the remote one.
 
 This is a problem, for example, when the application is running on a server
 and is written to upload or to otherwise provide the transferred data to a
@@ -56,7 +56,7 @@ SOLUTION
 
 libcurl 7.19.4 introduces a new option called `CURLOPT_REDIR_PROTOCOLS`, which
 applications can use to tell libcurl what target protocols automatic redirect
-followings are allowed to use. This will by default exclude FILE and SCP URLs.
+followings are allowed to use. By default this excludes FILE and SCP URLs.
 
 - Fixed-in: https://github.com/curl/curl/commit/042cc1f69ec0878f542667cb6843
 

docs/CVE-2010-0734.md

@@ -8,10 +8,9 @@ VULNERABILITY
 -------------
 
 When downloading data, libcurl hands it over to the application using a
-callback that is registered by the client software. libcurl will then call
-that function repeatedly with data until the transfer is complete. The
-callback is documented to receive a maximum data size of 16K
-(`CURL_MAX_WRITE_SIZE`).
+callback that is registered by the client software. libcurl then calls that
+function repeatedly with data until the transfer is complete. The callback is
+documented to receive a maximum data size of 16K (`CURL_MAX_WRITE_SIZE`).
 
 Using the affected libcurl version to download compressed content over HTTP,
 an application can ask libcurl to automatically uncompress data. When doing

docs/CVE-2010-3842.md

@@ -8,17 +8,17 @@ VULNERABILITY
 -------------
 
 curl offers a command line option --remote-header-name (also usable as -J)
-which will use the file name of the Content-disposition: header when it
-saves the downloaded data locally.
+which uses the filename of the Content-disposition: header when it saves the
+downloaded data locally.
 
-curl attempts to cut off the directory parts from any given file name in the
-header to only store files in the current directory. It will overwrite a
+curl attempts to cut off the directory parts from any given filename in the
+header to only store files in the current directory. It might overwrite a
 local file using the same name as the header specifies.
 
 The stripping of the directory did not take backslashes into account. On
 some operating systems, backslashes are used to separate directories and
-file names. This allows a rogue server to send back a response that
-overwrites a file name in the local machine that the user is allowed to
+filenames. This allows a rogue server to send back a response that
+overwrites a filename in the local machine that the user is allowed to
 write, potentially a system file, a command or a known executable.
 
 Operating systems affected include Windows, Netware, MSDOS, OS/2 and
@@ -50,7 +50,7 @@ such.
 SOLUTION
 --------
 
-libcurl 7.21.2 makes sure that it will also strip off paths specified using
+libcurl 7.21.2 makes sure that it also strips off paths specified using
 backslashes as path separator.
 
 - Fixed-in: https://github.com/curl/curl/commit/81f151c912105ded480c3c88a1

docs/CVE-2011-2192.md

@@ -15,7 +15,7 @@ operation, which should only be done when the user explicitly so directs.
 
 The GSS/Negotiate feature is only used by libcurl for HTTP authentication if
 told to, and only if libcurl was built with a library that provides the
-GSSAPI. Many builds of libcurl don't have GSS enabled.
+GSSAPI. Many builds of libcurl do not have GSS enabled.
 
 INFO
 ----

docs/CVE-2011-3389.md

@@ -7,20 +7,20 @@ Project curl Security Advisory, January 24th 2012
 VULNERABILITY
 -------------
 
-  curl is vulnerable to a SSL CBC IV vulnerability when built to use OpenSSL
-  for the SSL/TLS layer.
+curl is vulnerable to a SSL CBC IV vulnerability when built to use OpenSSL for
+the SSL/TLS layer.
 
-  This vulnerability has been identified (CVE-2011-3389 aka the "BEAST"
-  attack) and is addressed by OpenSSL already as they have made a work-around
-  to mitigate the problem.  When doing so, they figured out that some servers
-  didn't work with the work-around and offered a way to disable it.
+This vulnerability has been identified (CVE-2011-3389 aka the "BEAST" attack)
+and is addressed by OpenSSL already as they have made a work-around to
+mitigate the problem. When doing so, they figured out that some servers did
+not work with the work-around and offered a way to disable it.
 
-  The bit used to disable the workaround was then added to the generic
-  `SSL_OP_ALL` bitmask that SSL clients may use to enable workarounds for
-  better compatibility with servers. libcurl uses the SSL_OP_ALL bitmask.
+The bit used to disable the workaround was then added to the generic
+`SSL_OP_ALL` bitmask that SSL clients may use to enable workarounds for better
+compatibility with servers. libcurl uses the SSL_OP_ALL bitmask.
 
-  While `SSL_OP_ALL` is documented to enable "rather harmless" workarounds, it
-  does in this case effectively enable this security vulnerability again.
+While `SSL_OP_ALL` is documented to enable "rather harmless" workarounds, it
+does in this case effectively enable this security vulnerability again.
 
 INFO
 ----

docs/CVE-2012-0036.md

@@ -14,10 +14,10 @@ When parsing URLs, libcurl's parser is liberal and only parses as little as
 possible and lets as much as possible through as long as it can figure out
 what to do.
 
-In the specific process when libcurl extracts the file path part from a
-given URL, it didn't always verify the data or escape control characters
-properly before it passed the file path on to the protocol-specific code
-that then would use it for its protocol business.
+In the specific process when libcurl extracts the file path part from a given
+URL, it did not always verify the data or escape control characters properly
+before it passed the file path on to the protocol-specific code that then
+would use it for its protocol business.
 
 This passing through of control characters could be exploited by someone who
 would be able to pass in a handcrafted URL to libcurl. Lots of libcurl
@@ -77,7 +77,7 @@ RECOMMENDATIONS
   C - Rebuild curl with support for vulnerable protocols IMAP, POP3 and SMTP
       disabled.
 
-  D - Disable the vulnerable protocols IMAP, POP3 and SMTP at run-time to
+  D - Disable the vulnerable protocols IMAP, POP3 and SMTP at runtime to
       forbid libcurl from using them. You can do this with the
       CURLOPT_PROTOCOLS option.
 

docs/CVE-2013-0249.md

@@ -50,7 +50,7 @@ AFFECTED VERSIONS
 SOLUTION
 --------
 
-  libcurl 7.29.0 implements proper bounds checking and will not overflow any
+  libcurl 7.29.0 implements proper bounds checking and does not overflow any
   buffers even if unrealistically long data chunks are received.
 
 - Fixed-in: https://github.com/curl/curl/commit/f206d6c055d1008f0edb6d5d
@@ -68,7 +68,7 @@ RECOMMENDATIONS
   C - Rebuild curl with support for vulnerable protocols IMAP, POP3 and SMTP
       disabled.
 
-  D - Disable the vulnerable protocols IMAP, POP3 and SMTP at run-time to
+  D - Disable the vulnerable protocols IMAP, POP3 and SMTP at runtime to
       forbid libcurl from using them. You can do this with the
       CURLOPT_PROTOCOLS option.