pubrules 0.48.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. pubrules/__init__.py +14 -0
  2. pubrules/audit.py +116 -0
  3. pubrules/audit_draft.py +295 -0
  4. pubrules/audit_prepare.py +1128 -0
  5. pubrules/cache.py +319 -0
  6. pubrules/cbor.py +45 -0
  7. pubrules/ci.py +910 -0
  8. pubrules/cli.py +1069 -0
  9. pubrules/conform.py +295 -0
  10. pubrules/doc_coverage.py +235 -0
  11. pubrules/freshness.py +75 -0
  12. pubrules/gherkin.py +348 -0
  13. pubrules/hooks.py +59 -0
  14. pubrules/hosting.py +372 -0
  15. pubrules/ignores.py +86 -0
  16. pubrules/new.py +242 -0
  17. pubrules/nightly.py +1002 -0
  18. pubrules/paths.py +32 -0
  19. pubrules/protect.py +596 -0
  20. pubrules/providers.py +129 -0
  21. pubrules/refs.py +213 -0
  22. pubrules/release-commit +1 -0
  23. pubrules/releases.py +107 -0
  24. pubrules/repos.py +67 -0
  25. pubrules/ruleset.json +43 -0
  26. pubrules/secrets_config.py +165 -0
  27. pubrules/security.py +134 -0
  28. pubrules/service_needs.py +467 -0
  29. pubrules/standard.json +635 -0
  30. pubrules/standard.py +266 -0
  31. pubrules/supply_chain.py +188 -0
  32. pubrules/tag-ruleset.json +14 -0
  33. pubrules/templates/common/AGENTS.md +32 -0
  34. pubrules/templates/common/pubrules +26 -0
  35. pubrules/templates/common/tests/features/repository.feature +11 -0
  36. pubrules/templates/common/tests/install-lock +65 -0
  37. pubrules/templates/common/tests/pytest.ini +4 -0
  38. pubrules/templates/common/tests/requirements-pubrules.txt +17 -0
  39. pubrules/templates/common/tests/requirements.txt +3 -0
  40. pubrules/templates/common/tests/steps/test_repository.py +14 -0
  41. pubrules/templates/deploy/pubdeploy +28 -0
  42. pubrules/templates/new-rust/CHANGELOG.md +3 -0
  43. pubrules/templates/new-rust/Cargo.toml +46 -0
  44. pubrules/templates/new-rust/LICENSE +202 -0
  45. pubrules/templates/new-rust/Makefile +18 -0
  46. pubrules/templates/new-rust/README.md +34 -0
  47. pubrules/templates/new-rust/SECURITY.md +26 -0
  48. pubrules/templates/new-rust/corpus/corpus.json +11 -0
  49. pubrules/templates/new-rust/deny.toml +32 -0
  50. pubrules/templates/new-rust/fuzz/Cargo.toml +23 -0
  51. pubrules/templates/new-rust/fuzz/fuzz_targets/greet.rs +8 -0
  52. pubrules/templates/new-rust/fuzz/gitignore +4 -0
  53. pubrules/templates/new-rust/fuzz/regressions/README.md +4 -0
  54. pubrules/templates/new-rust/gitignore +10 -0
  55. pubrules/templates/new-rust/src/lib.rs +91 -0
  56. pubrules/templates/new-rust/src/main.rs +19 -0
  57. pubrules/templates/new-rust/supply-chain/audits.toml +4 -0
  58. pubrules/templates/new-rust/supply-chain/config.toml +23 -0
  59. pubrules/templates/new-rust/supply-chain/imports.lock +2 -0
  60. pubrules/templates/new-rust/tests/conftest.py +9 -0
  61. pubrules/templates/new-rust/tests/features/cli.feature +14 -0
  62. pubrules/templates/new-rust/tests/steps/test_cli.py +15 -0
  63. pubrules/templates/new-rust/tests/vectors.rs +30 -0
  64. pubrules/templates/new-rust/tools/vectors/generate.py +24 -0
  65. pubrules/templates/python/Makefile +5 -0
  66. pubrules/templates/python/pubrules-python.mk +47 -0
  67. pubrules/templates/rust/Makefile +9 -0
  68. pubrules/templates/rust/pubrules.mk +138 -0
  69. pubrules/templates/rust/rust-toolchain.toml +8 -0
  70. pubrules/templates/service/pubsec +27 -0
  71. pubrules/templates/service/with-secrets +20 -0
  72. pubrules/templates/service/with-secrets.json +8 -0
  73. pubrules/variables.py +45 -0
  74. pubrules-0.48.0.dist-info/METADATA +1241 -0
  75. pubrules-0.48.0.dist-info/RECORD +79 -0
  76. pubrules-0.48.0.dist-info/WHEEL +5 -0
  77. pubrules-0.48.0.dist-info/entry_points.txt +2 -0
  78. pubrules-0.48.0.dist-info/licenses/LICENSE +202 -0
  79. pubrules-0.48.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,165 @@
1
+ """What pubrules reads about secrets, never a value: pubrules.json's `github_app`
2
+ and `secrets` blocks, which name the values a repository needs and where they
3
+ go on GitHub, and its `signing_keys` block, which names each signing key and
4
+ where it is backed up. `pubrules sync --check` validates them, and pubdeploy's
5
+ walk implies its github.* needs from them, with its own copy of plan.
6
+
7
+ The commands that send, write or back up those values are pubsec's (`./pubsec
8
+ app-secrets`, `github-app create`, `signing-key backup`), which keep their
9
+ own copy of what they need of this: env_name, wrong_value and plan.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ import re
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ BLOCK = "github_app"
20
+ OTHERS = "secrets"
21
+ KINDS = {"secret", "variable"}
22
+ # Each of the three: how it goes to GitHub, and what its value looks like.
23
+ SLOTS = {"id": "variable", "installation_id": "variable", "key": "secret"}
24
+ FROM = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]*")
25
+ TO = re.compile(r"[A-Z_][A-Z0-9_]*")
26
+ ENVIRONMENT = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]*")
27
+
28
+
29
+ def app_problems(block: Any) -> list[str]:
30
+ """What is wrong with one app's three values: one phrase each."""
31
+ if not isinstance(block, dict):
32
+ return ["it must be an object, with id, installation_id and key"]
33
+ out = [f"{key} is not a setting; it takes id, installation_id and key"
34
+ for key in sorted(block.keys() - SLOTS.keys())]
35
+ for slot in SLOTS:
36
+ given = block.get(slot)
37
+ if not isinstance(given, dict) or set(given) != {"from", "to"}:
38
+ out.append(f"{slot} needs \"from\", its Bitwarden name, and \"to\", its GitHub name")
39
+ continue
40
+ if not isinstance(given["from"], str) or not FROM.fullmatch(given["from"]):
41
+ out.append(f"{slot}'s \"from\" is not a secret's name")
42
+ name = given["to"]
43
+ if not isinstance(name, str) or not TO.fullmatch(name) or name.startswith("GITHUB_"):
44
+ out.append(f"{slot}'s \"to\" must be upper case letters, digits and _, "
45
+ f"not starting GITHUB_")
46
+ return out
47
+
48
+
49
+ def problems(block: Any) -> list[str]:
50
+ """What is wrong with a github_app block, one app or a list of them."""
51
+ if isinstance(block, list) and block:
52
+ return [problem for app in block for problem in app_problems(app)]
53
+ if isinstance(block, list):
54
+ return ["it lists no apps"]
55
+ return app_problems(block)
56
+
57
+
58
+ def other_problems(entries: Any) -> list[str]:
59
+ """What is wrong with a secrets list: one phrase each, none when sound."""
60
+ if not isinstance(entries, list):
61
+ return ["it must be a list of from, to and kind"]
62
+ out = []
63
+ for entry in entries:
64
+ if not isinstance(entry, dict) or set(entry) - {"environment"} != {"from", "to", "kind"}:
65
+ out.append(f"{json.dumps(entry)} needs \"from\", \"to\" and \"kind\", and may have \"environment\"")
66
+ continue
67
+ label = entry["to"] if isinstance(entry["to"], str) else json.dumps(entry["to"])
68
+ if not isinstance(entry["from"], str) or not FROM.fullmatch(entry["from"]):
69
+ out.append(f"{label}'s \"from\" is not a secret's name")
70
+ if not isinstance(entry["to"], str) or not TO.fullmatch(entry["to"]) or entry["to"].startswith("GITHUB_"):
71
+ out.append(f"{label}'s \"to\" must be upper case letters, digits and _, not starting GITHUB_")
72
+ if not isinstance(entry["kind"], str) or entry["kind"] not in KINDS:
73
+ out.append(f"{label}'s \"kind\" must be secret or variable")
74
+ if "environment" in entry and not (isinstance(entry["environment"], str) and ENVIRONMENT.fullmatch(entry["environment"])):
75
+ out.append(f"{label}'s \"environment\" is not an environment's name")
76
+ return out
77
+
78
+
79
+ def plan(config: dict) -> list[dict]:
80
+ """Everything the config names: from, to, kind, and what its value must look like."""
81
+ block = config.get(BLOCK, [])
82
+ apps = block if isinstance(block, list) else [block]
83
+ out = [{"from": app[slot]["from"], "to": app[slot]["to"], "kind": kind, "check": slot}
84
+ for app in apps for slot, kind in SLOTS.items()]
85
+ return out + [{**entry, "check": None} for entry in config.get(OTHERS, [])]
86
+
87
+
88
+ def config_problems(config: dict) -> list[str]:
89
+ """What is wrong with both blocks, including one name used twice."""
90
+ out = []
91
+ if BLOCK in config:
92
+ out += [f"{BLOCK}: {p}" for p in problems(config[BLOCK])]
93
+ if OTHERS in config:
94
+ out += [f"{OTHERS}: {p}" for p in other_problems(config[OTHERS])]
95
+ if out:
96
+ return out
97
+ names = [(item["kind"], item["to"], item.get("environment", "")) for item in plan(config)]
98
+ return [f"two of them have the same \"to\", {to}" for kind, to, _ in sorted(set(names)) if names.count((kind, to, _)) > 1]
99
+
100
+
101
+ def wrong_value(slot: str | None, value: str) -> str | None:
102
+ """How a value isn't what it should be, without saying what it is."""
103
+ if not value:
104
+ return "is empty"
105
+ if slot in ("id", "installation_id") and not (value.isascii() and value.isdigit()):
106
+ return "is not an id: only digits are expected"
107
+ if slot == "key" and not (re.search(r"-----BEGIN [A-Z ]*PRIVATE KEY-----", value)
108
+ and re.search(r"-----END [A-Z ]*PRIVATE KEY-----", value)):
109
+ return "is not a private key: it needs its BEGIN and END lines"
110
+ return None
111
+
112
+
113
+ def env_name(name: str) -> str:
114
+ """The name with-secrets exports a secret under."""
115
+ return name.upper().replace("-", "_")
116
+
117
+
118
+ SIGNING_KEYS = "signing_keys"
119
+ NAME = re.compile(r"[A-Za-z][A-Za-z0-9_-]*")
120
+ UUID = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.I)
121
+
122
+
123
+ def signing_key_problems(block: object) -> list[str]:
124
+ """What is wrong with a pubrules.json `signing_keys` block: one phrase each."""
125
+ if block is None:
126
+ return []
127
+ if not isinstance(block, list):
128
+ return [f"{SIGNING_KEYS} must be a list"]
129
+ out: list[str] = []
130
+ names: set[tuple[str, str]] = set()
131
+ for i, entry in enumerate(block):
132
+ where = f"{SIGNING_KEYS}[{i}]"
133
+ if not isinstance(entry, dict):
134
+ out.append(f"{where} must be an object")
135
+ continue
136
+ out += [f"{where}: {key} is not a setting" for key in sorted(entry.keys() - {"path", "bitwarden"})]
137
+ path = entry.get("path")
138
+ if not (isinstance(path, str) and path.strip()):
139
+ out.append(f"{where} needs a path")
140
+ elif Path(path).is_absolute():
141
+ out.append(f"{where}: path is from the repository's root, or starts with ~/: {path}")
142
+ elif not path.startswith("~/") and ".." in Path(path).parts:
143
+ out.append(f"{where}: path leaves the repository: {path}")
144
+ bitwarden = entry.get("bitwarden")
145
+ if not isinstance(bitwarden, dict):
146
+ out.append(f"{where} needs bitwarden, with a project and a name")
147
+ continue
148
+ out += [f"{where}: bitwarden.{key} is not a setting" for key in sorted(bitwarden.keys() - {"project", "name"})]
149
+ project, name = bitwarden.get("project"), bitwarden.get("name")
150
+ if isinstance(project, dict):
151
+ out += [f"{where}: bitwarden.project.{key} is not a setting"
152
+ for key in sorted(project.keys() - {"id", "name"})]
153
+ if not (isinstance(project.get("id"), str) and UUID.fullmatch(project["id"])):
154
+ out.append(f"{where}: bitwarden.project.id must be the project's id, a UUID")
155
+ if "name" in project and not (isinstance(project["name"], str) and project["name"].strip()):
156
+ out.append(f"{where}: bitwarden.project.name, if given, is the project's name")
157
+ project = project.get("id")
158
+ elif not (isinstance(project, str) and project.strip()):
159
+ out.append(f"{where} needs bitwarden.project: {{\"id\": …, \"name\": …}}, or the project's id or name")
160
+ if not (isinstance(name, str) and NAME.fullmatch(name)):
161
+ out.append(f"{where}: bitwarden.name must be a letter, then letters, digits, _ and -")
162
+ elif (project, name) in names:
163
+ out.append(f"{where}: {name} is declared twice")
164
+ names.add((project, name))
165
+ return out
pubrules/security.py ADDED
@@ -0,0 +1,134 @@
1
+ """The `security` block of pubrules.json, beyond fuzzing (see nightly.py).
2
+
3
+ `security.dependabot` is the Dependabot configuration `pubrules sync` writes
4
+ to `.github/dependabot.yml`:
5
+
6
+ "dependabot": {"schedule": "weekly", "ecosystems": ["github-actions"],
7
+ "options": {"open-pull-requests-limit": 5}}
8
+
9
+ `schedule` is Dependabot's interval, `ecosystems` the package ecosystems it
10
+ updates, each at the repository's root unless given as Dependabot's own
11
+ `{"package-ecosystem": ..., "directory": ...}`, and `options` any other
12
+ Dependabot setting, added to every ecosystem's entry. The default is weekly
13
+ updates of the GitHub Actions alone: the nightly pull request updates the
14
+ languages, gated on CI, so Dependabot doing the same would open duplicate
15
+ pull requests. `"dependabot": false` leaves `.github/dependabot.yml` to the
16
+ repository.
17
+
18
+ Every github-actions entry ignores the owner's pubrules and pubrel workflows
19
+ and actions. Their pins move only with pubrules (`pubrules bump`), so
20
+ `pubrules sync --check` fails any pull request that moves one alone. Ignores
21
+ given in `options` are kept, after these.
22
+
23
+ Every github-actions entry also sets `open-pull-requests-limit` to 0, which
24
+ turns Dependabot's version updates off and leaves its security updates on:
25
+ the nightly moves the other actions (`pubrules actions`), on a branch that
26
+ can carry a pubrel row and gets a SonarQube Cloud token, which a Dependabot
27
+ pull request cannot. A repository whose pubrules.json sets `update.actions`
28
+ (or `update`) to false takes no nightly action updates, so Dependabot's
29
+ version updates stay on there, with any limit `options` gives.
30
+
31
+ `security.sonar` is `{"args": "-Dsonar.exclusions=vendor/**", "organization":
32
+ "example-org"}`: `args` are properties every workflow's sonar job adds, after
33
+ its `sonar-args` input, and `organization` is the SonarQube Cloud
34
+ organization key the scan sends the project to. By default that is the
35
+ GitHub owner in lower case, as SonarQube Cloud's keys are; the project key
36
+ stays `OWNER_REPO` with the owner as GitHub spells it.
37
+
38
+ The advisory checks (cargo deny, npm audit, pip-audit, OSV-Scanner,
39
+ dependency review) have no setting: every run makes them.
40
+ """
41
+
42
+ from __future__ import annotations
43
+
44
+ import json
45
+ import re
46
+ import sys
47
+ from typing import Any
48
+
49
+ from .refs import owner
50
+
51
+ DEPENDABOT_PATH = ".github/dependabot.yml"
52
+ SCHEDULES = ("daily", "weekly", "monthly")
53
+ DEPENDABOT = {"schedule": "weekly", "ecosystems": ["github-actions"], "options": {}}
54
+ # The owner's repositories whose workflows and actions `pubrules sync` and
55
+ # `pubrules bump` pin: Dependabot leaves them to pubrules.
56
+ PINNED = ("pubrules", "pubrel")
57
+ SONAR = ("args", "organization")
58
+ # SonarQube Cloud's organization keys: lower-case letters, digits and dashes.
59
+ ORGANIZATION = re.compile(r"[a-z0-9][a-z0-9-]*")
60
+
61
+
62
+ def block(config: dict[str, Any], name: str) -> Any:
63
+ security = config.get("security", {})
64
+ return security.get(name) if isinstance(security, dict) else None
65
+
66
+
67
+ def dependabot_settings(config: dict[str, Any]) -> dict[str, Any] | None:
68
+ """`security.dependabot` over the defaults, or None when it is false."""
69
+ given = block(config, "dependabot")
70
+ if given is False:
71
+ return None
72
+ given = {} if given is None else given
73
+ if not isinstance(given, dict):
74
+ sys.exit("pubrules: pubrules.json's security.dependabot must be an object, such as "
75
+ '{"schedule": "weekly"}, or false')
76
+ unknown = sorted(set(given) - set(DEPENDABOT))
77
+ if unknown:
78
+ sys.exit(f"pubrules: pubrules.json's security.dependabot has no setting {', '.join(unknown)}; "
79
+ f"it takes {', '.join(DEPENDABOT)}, and other Dependabot settings go in options")
80
+ out = {**DEPENDABOT, **given}
81
+ if out["schedule"] not in SCHEDULES:
82
+ sys.exit(f"pubrules: security.dependabot.schedule must be one of {', '.join(SCHEDULES)}, "
83
+ f"not {out['schedule']!r}")
84
+ ecosystems = out["ecosystems"]
85
+ if not isinstance(ecosystems, list) or not ecosystems or not all(
86
+ isinstance(e, str) or (isinstance(e, dict) and isinstance(e.get("package-ecosystem"), str))
87
+ for e in ecosystems):
88
+ sys.exit("pubrules: security.dependabot.ecosystems must list ecosystems, each a name such "
89
+ 'as "npm" or {"package-ecosystem": "pip", "directory": "/tests"}')
90
+ if not isinstance(out["options"], dict):
91
+ sys.exit("pubrules: security.dependabot.options must be an object of Dependabot settings")
92
+ return out
93
+
94
+
95
+ def dependabot(config: dict[str, Any]) -> str | None:
96
+ """The text of .github/dependabot.yml, or None when pubrules leaves it to
97
+ the repository. Each entry is JSON, which YAML reads as it is."""
98
+ settings = dependabot_settings(config)
99
+ if settings is None:
100
+ return None
101
+ from .nightly import UPDATES, by_language # noqa: PLC0415
102
+ nightly_moves = by_language("update", config.get("update", {}), UPDATES)["actions"]
103
+ pinned = [{"dependency-name": f"{owner(config)}/{name}/*"} for name in PINNED]
104
+ lines = ["# Written by `pubrules sync` from security.dependabot in pubrules.json. Do not edit:",
105
+ "# change pubrules.json and run `pubrules sync`.", "version: 2", "updates:"]
106
+ for ecosystem in settings["ecosystems"]:
107
+ entry = ({"package-ecosystem": ecosystem, "directory": "/"}
108
+ if isinstance(ecosystem, str) else {"directory": "/", **ecosystem})
109
+ entry = {**entry, "schedule": {"interval": settings["schedule"]}, **settings["options"]}
110
+ if entry["package-ecosystem"] == "github-actions":
111
+ given = entry.get("ignore", [])
112
+ entry["ignore"] = pinned + (given if isinstance(given, list) else [given])
113
+ if nightly_moves:
114
+ entry["open-pull-requests-limit"] = 0
115
+ lines.append(f" - {json.dumps(entry)}")
116
+ return "\n".join(lines) + "\n"
117
+
118
+
119
+ def sonar_settings(config: dict[str, Any]) -> dict[str, str]:
120
+ given = block(config, "sonar")
121
+ given = {} if given is None else given
122
+ if not isinstance(given, dict):
123
+ sys.exit('pubrules: pubrules.json\'s security.sonar must be an object, such as {"args": "..."}')
124
+ unknown = sorted(set(given) - set(SONAR))
125
+ if unknown:
126
+ sys.exit(f"pubrules: pubrules.json's security.sonar has no setting {', '.join(unknown)}; "
127
+ f"it takes {', '.join(SONAR)}")
128
+ if not isinstance(given.get("args", ""), str):
129
+ sys.exit("pubrules: security.sonar.args must be a string of -D properties")
130
+ organization = given.get("organization", "")
131
+ if organization != "" and not (isinstance(organization, str) and ORGANIZATION.fullmatch(organization)):
132
+ sys.exit("pubrules: security.sonar.organization must be a SonarQube Cloud organization key: "
133
+ "lower-case letters, digits and dashes, such as example-org")
134
+ return {"args": given.get("args", ""), "organization": organization}