sam-doctor 0.7.6__tar.gz
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.
- sam_doctor-0.7.6/LICENSE +21 -0
- sam_doctor-0.7.6/PKG-INFO +271 -0
- sam_doctor-0.7.6/README.md +244 -0
- sam_doctor-0.7.6/pyproject.toml +44 -0
- sam_doctor-0.7.6/setup.cfg +4 -0
- sam_doctor-0.7.6/src/sam_doctor/__init__.py +4 -0
- sam_doctor-0.7.6/src/sam_doctor/cli.py +272 -0
- sam_doctor-0.7.6/src/sam_doctor/data/api-gateway-no-methods-failure.txt +1 -0
- sam_doctor-0.7.6/src/sam_doctor/data/capability-acknowledgement-failure.txt +7 -0
- sam_doctor-0.7.6/src/sam_doctor/data/cloudformation-resource-failure.txt +2 -0
- sam_doctor-0.7.6/src/sam_doctor/data/esbuild-missing-failure.txt +1 -0
- sam_doctor-0.7.6/src/sam_doctor/data/interactive-changeset-failure.txt +2 -0
- sam_doctor-0.7.6/src/sam_doctor/data/oidc-assume-role-failure.txt +5 -0
- sam_doctor-0.7.6/src/sam_doctor/data/s3-bucket-conflict-failure.txt +1 -0
- sam_doctor-0.7.6/src/sam_doctor/diagnostics.py +667 -0
- sam_doctor-0.7.6/src/sam_doctor/redaction.py +38 -0
- sam_doctor-0.7.6/src/sam_doctor.egg-info/PKG-INFO +271 -0
- sam_doctor-0.7.6/src/sam_doctor.egg-info/SOURCES.txt +28 -0
- sam_doctor-0.7.6/src/sam_doctor.egg-info/dependency_links.txt +1 -0
- sam_doctor-0.7.6/src/sam_doctor.egg-info/entry_points.txt +2 -0
- sam_doctor-0.7.6/src/sam_doctor.egg-info/requires.txt +4 -0
- sam_doctor-0.7.6/src/sam_doctor.egg-info/top_level.txt +1 -0
- sam_doctor-0.7.6/tests/test_action_wrapper.py +9 -0
- sam_doctor-0.7.6/tests/test_check_outreach.py +262 -0
- sam_doctor-0.7.6/tests/test_diagnostics.py +428 -0
- sam_doctor-0.7.6/tests/test_distribution_checker.py +229 -0
- sam_doctor-0.7.6/tests/test_launch_check.py +402 -0
- sam_doctor-0.7.6/tests/test_launch_readiness.py +243 -0
- sam_doctor-0.7.6/tests/test_release_workflows.py +51 -0
- sam_doctor-0.7.6/tests/test_site_metadata.py +34 -0
sam_doctor-0.7.6/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jacob Goldstein
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sam-doctor
|
|
3
|
+
Version: 0.7.6
|
|
4
|
+
Summary: Local, evidence-first diagnostics for AWS SAM and GitHub Actions deployment failures.
|
|
5
|
+
Author: Jacob Goldstein
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://jakegold1647.github.io/sam-doctor/
|
|
8
|
+
Project-URL: Repository, https://github.com/jakegold1647/sam-doctor
|
|
9
|
+
Project-URL: Issues, https://github.com/jakegold1647/sam-doctor/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/jakegold1647/sam-doctor/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: aws,cloudformation,github-actions,iam,sam,serverless
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: build>=1; extra == "dev"
|
|
25
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
26
|
+
Dynamic: license-file
|
|
27
|
+
|
|
28
|
+
# SAM Doctor
|
|
29
|
+
|
|
30
|
+
[](https://github.com/jakegold1647/sam-doctor/actions/workflows/ci.yml)
|
|
31
|
+
[](LICENSE)
|
|
32
|
+
[](https://www.python.org/)
|
|
33
|
+
[](https://github.com/marketplace/actions/sam-doctor-aws-deployment-diagnostics)
|
|
34
|
+
[](https://github.com/jakegold1647/sam-doctor/releases)
|
|
35
|
+
|
|
36
|
+
SAM Doctor is a local, evidence-first command-line tool for turning AWS SAM,
|
|
37
|
+
CloudFormation, IAM, and GitHub Actions deployment failures into a concise
|
|
38
|
+
diagnostic report.
|
|
39
|
+
|
|
40
|
+
**[See the project page](https://jakegold1647.github.io/sam-doctor/)** |
|
|
41
|
+
**[Use on GitHub Marketplace](https://github.com/marketplace/actions/sam-doctor-aws-deployment-diagnostics)** |
|
|
42
|
+
**[Report a bad diagnosis](https://github.com/jakegold1647/sam-doctor/issues/new/choose)** |
|
|
43
|
+
**[Request a rule](https://github.com/jakegold1647/sam-doctor/issues/new/choose)** |
|
|
44
|
+
**[Join the feedback discussion](https://github.com/jakegold1647/sam-doctor/discussions/1)**
|
|
45
|
+
|
|
46
|
+
It does **not** access AWS, upload logs, change resources, or promise an
|
|
47
|
+
authoritative root cause. It detects known patterns in the text you provide,
|
|
48
|
+
redacts common identifiers, and gives safe verification steps and the relevant
|
|
49
|
+
official documentation.
|
|
50
|
+
|
|
51
|
+
Current release: **v0.7.6**.
|
|
52
|
+
|
|
53
|
+
## Current free core
|
|
54
|
+
|
|
55
|
+
- GitHub Actions OIDC errors: missing `id-token: write`, audience mismatch,
|
|
56
|
+
trust-policy/subject mismatch, and `AssumeRoleWithWebIdentity` failures
|
|
57
|
+
- IAM `AccessDenied` failures
|
|
58
|
+
- CloudFormation failed-resource events and rollback states
|
|
59
|
+
- CloudFormation capability acknowledgement errors
|
|
60
|
+
- API Gateway deployments created before methods exist
|
|
61
|
+
- SAM deployment/configuration errors, including conflicting artifact-bucket settings
|
|
62
|
+
and missing `esbuild` dependencies
|
|
63
|
+
- Template shape, IAM trust-policy, Lambda packaging, and S3 artifact failures
|
|
64
|
+
- API Gateway CORS preflight conflicts
|
|
65
|
+
- Terminal, Markdown, and JSON reports
|
|
66
|
+
- Composite GitHub Action with opt-in redacted job summaries and CI gating
|
|
67
|
+
- Local redaction for account IDs, ARNs, email addresses, and common CI credentials
|
|
68
|
+
|
|
69
|
+
## Try it in 60 seconds
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
python -m pip install https://github.com/jakegold1647/sam-doctor/releases/download/v0.7.6/sam_doctor-0.7.6-py3-none-any.whl
|
|
73
|
+
sam-doctor demo
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
This installs the stable v0.7.6 wheel directly from GitHub and does not require
|
|
77
|
+
Git. The bundled demo needs no AWS credentials and makes no network calls. To install
|
|
78
|
+
from the tagged source instead, run:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
python -m pip install "sam-doctor @ git+https://github.com/jakegold1647/sam-doctor.git@v0.7.6"
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
If your shell cannot find `sam-doctor` after installation, activate the
|
|
85
|
+
environment where it was installed or use `python -m sam_doctor.cli` in the
|
|
86
|
+
commands below.
|
|
87
|
+
|
|
88
|
+
For more bundled examples, try `sam-doctor demo --scenario cloudformation`,
|
|
89
|
+
`sam-doctor demo --scenario api-gateway`, or `sam-doctor demo --scenario esbuild`.
|
|
90
|
+
Run `sam-doctor rules --format json` to inspect the exact set of supported
|
|
91
|
+
diagnostic categories before sharing a log.
|
|
92
|
+
|
|
93
|
+
To save a report:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
sam-doctor diagnose deployment.log --format markdown --output diagnosis.md
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The input can also be read from standard input, which is useful for CI steps and
|
|
100
|
+
shell pipelines:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
kubectl logs deploy/my-api | sam-doctor diagnose -
|
|
104
|
+
sam-doctor diagnose deployment.log --format json --output diagnosis.json
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The terminal format is intended for a quick local check, Markdown is convenient
|
|
108
|
+
for a human-readable handoff, and JSON is stable enough for scripts and CI
|
|
109
|
+
annotations. All three formats contain matched evidence rather than the full
|
|
110
|
+
input log.
|
|
111
|
+
|
|
112
|
+
You can also process multiple files in batch mode:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
sam-doctor batch logs/*.log logs/*.txt --format json > batch-results.json
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## GitHub Actions
|
|
119
|
+
|
|
120
|
+
Use the included action when a workflow already saves a deployment log:
|
|
121
|
+
|
|
122
|
+
```yaml
|
|
123
|
+
- name: Deploy
|
|
124
|
+
shell: bash
|
|
125
|
+
run: |
|
|
126
|
+
set -o pipefail
|
|
127
|
+
sam deploy --no-confirm-changeset 2>&1 | tee deployment.log
|
|
128
|
+
|
|
129
|
+
- name: Diagnose deployment log
|
|
130
|
+
if: always()
|
|
131
|
+
id: sam-doctor
|
|
132
|
+
uses: jakegold1647/sam-doctor@v0.7.6
|
|
133
|
+
with:
|
|
134
|
+
log-file: deployment.log
|
|
135
|
+
summary: "true"
|
|
136
|
+
# Uncomment to fail this job when a supported finding is detected.
|
|
137
|
+
# fail-on-findings: "true"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Put the diagnostic step after the command that writes the log and keep
|
|
141
|
+
`if: always()`; otherwise GitHub Actions skips it when the deployment fails.
|
|
142
|
+
The action exposes `finding-count` and `has-findings` outputs. Set
|
|
143
|
+
`fail-on-findings: "true"` only when you want a supported diagnostic to fail
|
|
144
|
+
the job; the commented line above shows the opt-in placement. The Markdown job
|
|
145
|
+
summary is opt-in and contains only matched, redacted
|
|
146
|
+
evidence; review it before sharing a workflow run outside your team.
|
|
147
|
+
|
|
148
|
+
## What a report includes
|
|
149
|
+
|
|
150
|
+
SAM Doctor deliberately reports only what its rules can support:
|
|
151
|
+
|
|
152
|
+
1. A likely failure category and confidence level.
|
|
153
|
+
2. Up to three matched log lines, redacted before output.
|
|
154
|
+
3. Safe checks to validate the diagnosis before changing a policy or stack.
|
|
155
|
+
4. A link to the relevant official documentation.
|
|
156
|
+
|
|
157
|
+
It is most useful when you start with the first failure in a deployment log,
|
|
158
|
+
not a later rollback message. When multiple supported patterns appear, SAM
|
|
159
|
+
Doctor presents findings in the order of their first matching log line.
|
|
160
|
+
|
|
161
|
+
## Example output
|
|
162
|
+
|
|
163
|
+
```text
|
|
164
|
+
Likely cause: GitHub Actions cannot assume the configured AWS role through OIDC.
|
|
165
|
+
Confidence: high
|
|
166
|
+
Evidence: Not authorized to perform sts:AssumeRoleWithWebIdentity
|
|
167
|
+
Safe next step: Confirm the workflow grants `id-token: write` and that the
|
|
168
|
+
role trust policy's `sub` condition matches the repository, branch, or GitHub
|
|
169
|
+
Environment that ran the job.
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Feedback and roadmap
|
|
173
|
+
|
|
174
|
+
The free core will stay useful for individual deployment failures. Please open
|
|
175
|
+
an issue when a report is wrong, unclear, or missing a failure pattern. For a
|
|
176
|
+
new rule, include only a sanitized error excerpt and the safe next check you
|
|
177
|
+
expected to see. See [CONTRIBUTING.md](CONTRIBUTING.md) for the exact format.
|
|
178
|
+
|
|
179
|
+
## Distribution and ethics
|
|
180
|
+
|
|
181
|
+
SAM Doctor is grown through practical conversations and feedback, not star
|
|
182
|
+
incentives. If you run outreach, ask for one realistic use case first, then
|
|
183
|
+
share the report and a short ask for permission to improve coverage.
|
|
184
|
+
|
|
185
|
+
Track progress with:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
python scripts/check-launch.py \
|
|
189
|
+
--append-csv artifacts/distribution.csv \
|
|
190
|
+
--summary artifacts/distribution-summary.md \
|
|
191
|
+
--print-trend
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Before release tagging, run:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
python scripts/check-launch.py --skip-outreach
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
For a lightweight outreach quality check, run:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
python scripts/check-launch.py \
|
|
204
|
+
--skip-distribution \
|
|
205
|
+
--outreach-summary artifacts/outreach-summary.md \
|
|
206
|
+
--outreach-log launch/outreach-log-template.csv
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
For a stricter organic-growth check:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
python scripts/check-outreach.py launch/outreach-log-template.csv \
|
|
213
|
+
--strict --min-feedback-ratio 100
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
For a combined snapshot, `scripts/check-launch.py` also writes
|
|
217
|
+
`artifacts/outreach-summary.md` with an `ethical_growth_score` and concrete
|
|
218
|
+
`next_growth_actions` to guide the next outreach batch.
|
|
219
|
+
|
|
220
|
+
For the ethical outreach loop, copy `launch/outreach-log-template.csv` into your
|
|
221
|
+
tracking notes and fill one row per real contact.
|
|
222
|
+
|
|
223
|
+
After a release is published and channels are expected live, run the stricter
|
|
224
|
+
combined gate:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
python scripts/check-launch.py \
|
|
228
|
+
--strict-distribution-during-release \
|
|
229
|
+
--strict-ethical --min-feedback-ratio 100 \
|
|
230
|
+
--outreach-log launch/outreach-log-template.csv \
|
|
231
|
+
--outreach-summary artifacts/outreach-summary.md
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
On stable releases, the PyPI publish workflow also kicks off a strict `distribution-check.yml`
|
|
235
|
+
run after package upload so the strict gate can be verified post-live without
|
|
236
|
+
blocking on early warm-up timing.
|
|
237
|
+
|
|
238
|
+
## Guides
|
|
239
|
+
|
|
240
|
+
- [Diagnose a GitHub Actions to AWS OIDC deployment failure](docs/oidc-deployment-debugging.md)
|
|
241
|
+
- [Find the first useful error in a CloudFormation rollback](docs/cloudformation-first-failure.md)
|
|
242
|
+
|
|
243
|
+
## Supported signals
|
|
244
|
+
|
|
245
|
+
Run `sam-doctor rules` for the current machine-readable catalog. Each rule is
|
|
246
|
+
triggered by an explicit error signal, not by template inspection or AWS account
|
|
247
|
+
access; the report is still a prompt to verify the cause, not an automatic fix.
|
|
248
|
+
|
|
249
|
+
## Scope and safety
|
|
250
|
+
|
|
251
|
+
Run this only on logs you are authorized to inspect. Review every suggested
|
|
252
|
+
command and policy change before applying it. SAM Doctor is diagnostic help,
|
|
253
|
+
not security, legal, or production-operations advice.
|
|
254
|
+
|
|
255
|
+
Reports redact AWS account IDs, ARNs, email addresses, common AWS access key IDs,
|
|
256
|
+
bearer tokens, JWT-style tokens, and common GitHub token formats before matched
|
|
257
|
+
evidence or a displayed source name is shared. This is a helpful guardrail, not a secret scanner:
|
|
258
|
+
review a report before sharing it.
|
|
259
|
+
|
|
260
|
+
## Development
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
python -m pip install -e ".[dev]"
|
|
264
|
+
python -m pytest -q
|
|
265
|
+
python -m build
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
See [CHANGELOG.md](CHANGELOG.md) for release history, [SECURITY.md](SECURITY.md)
|
|
269
|
+
for vulnerability reporting, [SUPPORT.md](SUPPORT.md) for help boundaries, and
|
|
270
|
+
[docs/pypi-publishing.md](docs/pypi-publishing.md) for the stable-release
|
|
271
|
+
publishing setup.
|
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# SAM Doctor
|
|
2
|
+
|
|
3
|
+
[](https://github.com/jakegold1647/sam-doctor/actions/workflows/ci.yml)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://www.python.org/)
|
|
6
|
+
[](https://github.com/marketplace/actions/sam-doctor-aws-deployment-diagnostics)
|
|
7
|
+
[](https://github.com/jakegold1647/sam-doctor/releases)
|
|
8
|
+
|
|
9
|
+
SAM Doctor is a local, evidence-first command-line tool for turning AWS SAM,
|
|
10
|
+
CloudFormation, IAM, and GitHub Actions deployment failures into a concise
|
|
11
|
+
diagnostic report.
|
|
12
|
+
|
|
13
|
+
**[See the project page](https://jakegold1647.github.io/sam-doctor/)** |
|
|
14
|
+
**[Use on GitHub Marketplace](https://github.com/marketplace/actions/sam-doctor-aws-deployment-diagnostics)** |
|
|
15
|
+
**[Report a bad diagnosis](https://github.com/jakegold1647/sam-doctor/issues/new/choose)** |
|
|
16
|
+
**[Request a rule](https://github.com/jakegold1647/sam-doctor/issues/new/choose)** |
|
|
17
|
+
**[Join the feedback discussion](https://github.com/jakegold1647/sam-doctor/discussions/1)**
|
|
18
|
+
|
|
19
|
+
It does **not** access AWS, upload logs, change resources, or promise an
|
|
20
|
+
authoritative root cause. It detects known patterns in the text you provide,
|
|
21
|
+
redacts common identifiers, and gives safe verification steps and the relevant
|
|
22
|
+
official documentation.
|
|
23
|
+
|
|
24
|
+
Current release: **v0.7.6**.
|
|
25
|
+
|
|
26
|
+
## Current free core
|
|
27
|
+
|
|
28
|
+
- GitHub Actions OIDC errors: missing `id-token: write`, audience mismatch,
|
|
29
|
+
trust-policy/subject mismatch, and `AssumeRoleWithWebIdentity` failures
|
|
30
|
+
- IAM `AccessDenied` failures
|
|
31
|
+
- CloudFormation failed-resource events and rollback states
|
|
32
|
+
- CloudFormation capability acknowledgement errors
|
|
33
|
+
- API Gateway deployments created before methods exist
|
|
34
|
+
- SAM deployment/configuration errors, including conflicting artifact-bucket settings
|
|
35
|
+
and missing `esbuild` dependencies
|
|
36
|
+
- Template shape, IAM trust-policy, Lambda packaging, and S3 artifact failures
|
|
37
|
+
- API Gateway CORS preflight conflicts
|
|
38
|
+
- Terminal, Markdown, and JSON reports
|
|
39
|
+
- Composite GitHub Action with opt-in redacted job summaries and CI gating
|
|
40
|
+
- Local redaction for account IDs, ARNs, email addresses, and common CI credentials
|
|
41
|
+
|
|
42
|
+
## Try it in 60 seconds
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
python -m pip install https://github.com/jakegold1647/sam-doctor/releases/download/v0.7.6/sam_doctor-0.7.6-py3-none-any.whl
|
|
46
|
+
sam-doctor demo
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
This installs the stable v0.7.6 wheel directly from GitHub and does not require
|
|
50
|
+
Git. The bundled demo needs no AWS credentials and makes no network calls. To install
|
|
51
|
+
from the tagged source instead, run:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
python -m pip install "sam-doctor @ git+https://github.com/jakegold1647/sam-doctor.git@v0.7.6"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
If your shell cannot find `sam-doctor` after installation, activate the
|
|
58
|
+
environment where it was installed or use `python -m sam_doctor.cli` in the
|
|
59
|
+
commands below.
|
|
60
|
+
|
|
61
|
+
For more bundled examples, try `sam-doctor demo --scenario cloudformation`,
|
|
62
|
+
`sam-doctor demo --scenario api-gateway`, or `sam-doctor demo --scenario esbuild`.
|
|
63
|
+
Run `sam-doctor rules --format json` to inspect the exact set of supported
|
|
64
|
+
diagnostic categories before sharing a log.
|
|
65
|
+
|
|
66
|
+
To save a report:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
sam-doctor diagnose deployment.log --format markdown --output diagnosis.md
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The input can also be read from standard input, which is useful for CI steps and
|
|
73
|
+
shell pipelines:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
kubectl logs deploy/my-api | sam-doctor diagnose -
|
|
77
|
+
sam-doctor diagnose deployment.log --format json --output diagnosis.json
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The terminal format is intended for a quick local check, Markdown is convenient
|
|
81
|
+
for a human-readable handoff, and JSON is stable enough for scripts and CI
|
|
82
|
+
annotations. All three formats contain matched evidence rather than the full
|
|
83
|
+
input log.
|
|
84
|
+
|
|
85
|
+
You can also process multiple files in batch mode:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
sam-doctor batch logs/*.log logs/*.txt --format json > batch-results.json
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## GitHub Actions
|
|
92
|
+
|
|
93
|
+
Use the included action when a workflow already saves a deployment log:
|
|
94
|
+
|
|
95
|
+
```yaml
|
|
96
|
+
- name: Deploy
|
|
97
|
+
shell: bash
|
|
98
|
+
run: |
|
|
99
|
+
set -o pipefail
|
|
100
|
+
sam deploy --no-confirm-changeset 2>&1 | tee deployment.log
|
|
101
|
+
|
|
102
|
+
- name: Diagnose deployment log
|
|
103
|
+
if: always()
|
|
104
|
+
id: sam-doctor
|
|
105
|
+
uses: jakegold1647/sam-doctor@v0.7.6
|
|
106
|
+
with:
|
|
107
|
+
log-file: deployment.log
|
|
108
|
+
summary: "true"
|
|
109
|
+
# Uncomment to fail this job when a supported finding is detected.
|
|
110
|
+
# fail-on-findings: "true"
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Put the diagnostic step after the command that writes the log and keep
|
|
114
|
+
`if: always()`; otherwise GitHub Actions skips it when the deployment fails.
|
|
115
|
+
The action exposes `finding-count` and `has-findings` outputs. Set
|
|
116
|
+
`fail-on-findings: "true"` only when you want a supported diagnostic to fail
|
|
117
|
+
the job; the commented line above shows the opt-in placement. The Markdown job
|
|
118
|
+
summary is opt-in and contains only matched, redacted
|
|
119
|
+
evidence; review it before sharing a workflow run outside your team.
|
|
120
|
+
|
|
121
|
+
## What a report includes
|
|
122
|
+
|
|
123
|
+
SAM Doctor deliberately reports only what its rules can support:
|
|
124
|
+
|
|
125
|
+
1. A likely failure category and confidence level.
|
|
126
|
+
2. Up to three matched log lines, redacted before output.
|
|
127
|
+
3. Safe checks to validate the diagnosis before changing a policy or stack.
|
|
128
|
+
4. A link to the relevant official documentation.
|
|
129
|
+
|
|
130
|
+
It is most useful when you start with the first failure in a deployment log,
|
|
131
|
+
not a later rollback message. When multiple supported patterns appear, SAM
|
|
132
|
+
Doctor presents findings in the order of their first matching log line.
|
|
133
|
+
|
|
134
|
+
## Example output
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
Likely cause: GitHub Actions cannot assume the configured AWS role through OIDC.
|
|
138
|
+
Confidence: high
|
|
139
|
+
Evidence: Not authorized to perform sts:AssumeRoleWithWebIdentity
|
|
140
|
+
Safe next step: Confirm the workflow grants `id-token: write` and that the
|
|
141
|
+
role trust policy's `sub` condition matches the repository, branch, or GitHub
|
|
142
|
+
Environment that ran the job.
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Feedback and roadmap
|
|
146
|
+
|
|
147
|
+
The free core will stay useful for individual deployment failures. Please open
|
|
148
|
+
an issue when a report is wrong, unclear, or missing a failure pattern. For a
|
|
149
|
+
new rule, include only a sanitized error excerpt and the safe next check you
|
|
150
|
+
expected to see. See [CONTRIBUTING.md](CONTRIBUTING.md) for the exact format.
|
|
151
|
+
|
|
152
|
+
## Distribution and ethics
|
|
153
|
+
|
|
154
|
+
SAM Doctor is grown through practical conversations and feedback, not star
|
|
155
|
+
incentives. If you run outreach, ask for one realistic use case first, then
|
|
156
|
+
share the report and a short ask for permission to improve coverage.
|
|
157
|
+
|
|
158
|
+
Track progress with:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
python scripts/check-launch.py \
|
|
162
|
+
--append-csv artifacts/distribution.csv \
|
|
163
|
+
--summary artifacts/distribution-summary.md \
|
|
164
|
+
--print-trend
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Before release tagging, run:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
python scripts/check-launch.py --skip-outreach
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
For a lightweight outreach quality check, run:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
python scripts/check-launch.py \
|
|
177
|
+
--skip-distribution \
|
|
178
|
+
--outreach-summary artifacts/outreach-summary.md \
|
|
179
|
+
--outreach-log launch/outreach-log-template.csv
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
For a stricter organic-growth check:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
python scripts/check-outreach.py launch/outreach-log-template.csv \
|
|
186
|
+
--strict --min-feedback-ratio 100
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
For a combined snapshot, `scripts/check-launch.py` also writes
|
|
190
|
+
`artifacts/outreach-summary.md` with an `ethical_growth_score` and concrete
|
|
191
|
+
`next_growth_actions` to guide the next outreach batch.
|
|
192
|
+
|
|
193
|
+
For the ethical outreach loop, copy `launch/outreach-log-template.csv` into your
|
|
194
|
+
tracking notes and fill one row per real contact.
|
|
195
|
+
|
|
196
|
+
After a release is published and channels are expected live, run the stricter
|
|
197
|
+
combined gate:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
python scripts/check-launch.py \
|
|
201
|
+
--strict-distribution-during-release \
|
|
202
|
+
--strict-ethical --min-feedback-ratio 100 \
|
|
203
|
+
--outreach-log launch/outreach-log-template.csv \
|
|
204
|
+
--outreach-summary artifacts/outreach-summary.md
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
On stable releases, the PyPI publish workflow also kicks off a strict `distribution-check.yml`
|
|
208
|
+
run after package upload so the strict gate can be verified post-live without
|
|
209
|
+
blocking on early warm-up timing.
|
|
210
|
+
|
|
211
|
+
## Guides
|
|
212
|
+
|
|
213
|
+
- [Diagnose a GitHub Actions to AWS OIDC deployment failure](docs/oidc-deployment-debugging.md)
|
|
214
|
+
- [Find the first useful error in a CloudFormation rollback](docs/cloudformation-first-failure.md)
|
|
215
|
+
|
|
216
|
+
## Supported signals
|
|
217
|
+
|
|
218
|
+
Run `sam-doctor rules` for the current machine-readable catalog. Each rule is
|
|
219
|
+
triggered by an explicit error signal, not by template inspection or AWS account
|
|
220
|
+
access; the report is still a prompt to verify the cause, not an automatic fix.
|
|
221
|
+
|
|
222
|
+
## Scope and safety
|
|
223
|
+
|
|
224
|
+
Run this only on logs you are authorized to inspect. Review every suggested
|
|
225
|
+
command and policy change before applying it. SAM Doctor is diagnostic help,
|
|
226
|
+
not security, legal, or production-operations advice.
|
|
227
|
+
|
|
228
|
+
Reports redact AWS account IDs, ARNs, email addresses, common AWS access key IDs,
|
|
229
|
+
bearer tokens, JWT-style tokens, and common GitHub token formats before matched
|
|
230
|
+
evidence or a displayed source name is shared. This is a helpful guardrail, not a secret scanner:
|
|
231
|
+
review a report before sharing it.
|
|
232
|
+
|
|
233
|
+
## Development
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
python -m pip install -e ".[dev]"
|
|
237
|
+
python -m pytest -q
|
|
238
|
+
python -m build
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
See [CHANGELOG.md](CHANGELOG.md) for release history, [SECURITY.md](SECURITY.md)
|
|
242
|
+
for vulnerability reporting, [SUPPORT.md](SUPPORT.md) for help boundaries, and
|
|
243
|
+
[docs/pypi-publishing.md](docs/pypi-publishing.md) for the stable-release
|
|
244
|
+
publishing setup.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "sam-doctor"
|
|
7
|
+
version = "0.7.6"
|
|
8
|
+
description = "Local, evidence-first diagnostics for AWS SAM and GitHub Actions deployment failures."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{name = "Jacob Goldstein"}]
|
|
13
|
+
keywords = ["aws", "cloudformation", "github-actions", "iam", "sam", "serverless"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Programming Language :: Python :: 3.10",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Homepage = "https://jakegold1647.github.io/sam-doctor/"
|
|
27
|
+
Repository = "https://github.com/jakegold1647/sam-doctor"
|
|
28
|
+
Issues = "https://github.com/jakegold1647/sam-doctor/issues"
|
|
29
|
+
Changelog = "https://github.com/jakegold1647/sam-doctor/blob/main/CHANGELOG.md"
|
|
30
|
+
|
|
31
|
+
[project.scripts]
|
|
32
|
+
sam-doctor = "sam_doctor.cli:main"
|
|
33
|
+
|
|
34
|
+
[project.optional-dependencies]
|
|
35
|
+
dev = ["build>=1", "pytest>=8"]
|
|
36
|
+
|
|
37
|
+
[tool.setuptools.packages.find]
|
|
38
|
+
where = ["src"]
|
|
39
|
+
|
|
40
|
+
[tool.setuptools.package-data]
|
|
41
|
+
sam_doctor = ["data/*.txt"]
|
|
42
|
+
|
|
43
|
+
[tool.pytest.ini_options]
|
|
44
|
+
testpaths = ["tests"]
|