Skip to content

Commit 0ce6221

Browse files
woodruffwwoodruffw
authored
feat: begin prepping zizmor's website (#78)
1 parent b25a5bf commit 0ce6221

25 files changed

+706
-411
lines changed

Diff for: ‎.github/workflows/site.yml

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Deploy zizmor site
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- site-staging
8+
9+
workflow_dispatch:
10+
11+
concurrency:
12+
group: "pages"
13+
cancel-in-progress: false
14+
15+
permissions: {}
16+
17+
jobs:
18+
deploy:
19+
permissions:
20+
contents: read
21+
pages: write
22+
id-token: write
23+
environment:
24+
name: github-pages
25+
url: ${{ steps.deployment.outputs.page_url }}
26+
27+
runs-on: ubuntu-latest
28+
steps:
29+
- uses: actions/checkout@v4
30+
with:
31+
persist-credentials: false
32+
33+
- name: Install the latest version of uv
34+
uses: astral-sh/setup-uv@v3
35+
36+
- name: build site
37+
run: make site
38+
39+
- name: Setup Pages
40+
uses: actions/configure-pages@v5
41+
42+
- name: Upload artifact
43+
uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: site_html
46+
47+
- name: Deploy to GitHub Pages
48+
id: deployment
49+
uses: actions/deploy-pages@v4

Diff for: ‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -1 +1,4 @@
11
/target
2+
3+
# website artifacts
4+
/site_html

Diff for: ‎CONTRIBUTING.md

+62-47
Original file line numberDiff line numberDiff line change
@@ -2,69 +2,84 @@
22

33
Thank you for your interest in contributing to `zizmor`!
44

5-
The information below will help you set up a local development environment,
6-
as well as with performing common development tasks.
5+
This is intended to be a "high-level" guide with some suggestions
6+
for ways to contribute. Once you've picked a contribution idea,
7+
please see our [development docs]
8+
for concrete guidance on specific development tasks (such as building `zizmor`
9+
itself or the documentation website).
710

8-
This is intended to be a "high-level" guide; for concrete development
9-
goals (such as modifying an audit or contributing a new audit),
10-
please see our [development docs](./docs/DEVELOPMENT.md).
11+
## How to contribute
1112

12-
## Requirements
13+
Here's a short list of steps you can follow to contribute:
1314

14-
`zizmor`'s only development requirement the Rust compiler.
15+
1. *Figure out what you want to contribute.* See the
16+
[contribution ideas](#contribution-ideas) section below if you're looking
17+
for ideas!
18+
2. *File or reply to an issue, if appropriate.* Some contributions require
19+
new issues (like new bugs), while others involve an existing issue
20+
(like known documentation defects). Others don't require an issue at all,
21+
like small typo fixes. In general, if you aren't sure, *error on the side
22+
of making or replying to an issue* — it helps maintain shared
23+
development context.
24+
3. *Hack away.* Once you know what you're working on, refer to our
25+
[development docs] for help with specific development tasks. And don't be
26+
afraid to ask for help!
1527

16-
You can install Rust by following the steps on [Rust's official website].
28+
## Contribution ideas
1729

18-
[Rust's official website]: https://www.rust-lang.org/tools/install
30+
Here are some ways that you can contribute to `zizmor`. These aren't the only
31+
ways; they're just for inspiration.
1932

20-
## Development steps
33+
### Good first issues
2134

22-
To get started, you'll need to clone the repository and perform a debug build:
35+
We use the ["good first issue"] label to track issues that we think are
36+
(somewhat) easy and/or straightforward, making them good choices for an
37+
early contribution.
2338

24-
```bash
25-
git clone https://github.com/woodruffw/zizmor
26-
cd zizmor
27-
cargo build
28-
```
39+
To work on one of these, **please leave a comment** on its issue before opening
40+
a pull request to make sure nobody else duplicates your work!
2941

30-
Once `cargo build` completes, you should have a functional development
31-
build of `zizmor`!
42+
["good first issue"]: https://github.com/woodruffw/zizmor/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
3243

33-
```bash
34-
# cargo run -- --help also works
35-
./target/debug/zizmor --help
36-
```
44+
### Writing documentation
3745

38-
## Linting
46+
One of the best ways to help us with `zizmor` is to help us improve our
47+
documentation!
3948

40-
`zizmor` is linted with `cargo clippy` and auto-formatted with `cargo fmt`.
41-
Our CI enforces both, but you should also run them locally to minimize
42-
unnecessary review cycles:
49+
Here are some things we could use help with:
4350

44-
```bash
45-
cargo fmt
46-
cargo clippy --fix
47-
```
51+
* Improving our [CLI usage recipes](https://woodruffw.github.io/zizmor/usage/).
52+
* Improving the detail in our
53+
[audit documentation pages](https://woodruffw.github.io/zizmor/audits/).
54+
* Improving our internal (Rust API) documentation, especially in conjunction
55+
with more unit tests.
4856

49-
## Testing
57+
More generally, see [issues labeled with `documentation`] for a potential
58+
list of documentation efforts to contribute on.
5059

51-
`zizmor` uses `cargo test`:
60+
[issues labeled with `documentation`]: https://github.com/woodruffw/zizmor/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation
5261

53-
```bash
54-
cargo test
55-
```
62+
### Writing unit tests
5663

57-
## Development practices
64+
We can always use more unit tests! Pick a part of the Rust codebase and
65+
start testing.
5866

59-
Here are some guidelines to follow if you're working on `zizmor`:
67+
Keep the cardinal rule of unit testing in mind: a unit test must test
68+
**a single unit** of behavior. If it tests more than one unit, then
69+
consider making it an integration test instead.
70+
71+
### Reducing false positives/negatives in audits
72+
73+
Static analysis is inherently imprecise, and `zizmor` is no exception.
74+
75+
We track imprecision bugs with the ["false positive"] and ["false negative"]
76+
labels. These can sometimes be tricky to address, so we recommend
77+
(but don't require) leaving an explanatory comment on the issue before
78+
beginning a pull request.
79+
80+
["false positive"]: https://github.com/woodruffw/zizmor/issues?q=is%3Aopen+label%3Afalse-positive
81+
82+
["false negative"]: https://github.com/woodruffw/zizmor/issues?q=is%3Aopen+label%3Afalse-negative
83+
84+
[development docs]: https://woodruffw.github.io/zizmor/development/
6085

61-
* *Document internal APIs*. `zizmor` doesn't have a public Rust API (yet),
62-
but the internal APIs should be documented *as if* they might become public
63-
one day. Plus, well-documented internals make life easier for new
64-
contributors.
65-
* *Write unit tests*. It's easy for small changes in `zizmor`'s internals to
66-
percolate into large bugs (e.g. incorrect location information); help us
67-
catch these bugs earlier by testing your changes at the smallest unit of
68-
behavior.
69-
* *Test on real inputs*. If you're contributing to or adding a new audit,
70-
make sure your analysis is reliable and accurate on non-sample inputs.

Diff for: ‎Makefile

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
VENV = .venv
2+
VENV_BIN := $(VENV)/bin
3+
4+
.PHONY: all
5+
all:
6+
@echo "Run my targets individually!"
7+
8+
.PHONY: site
9+
site: $(VENV)
10+
$(VENV_BIN)/mkdocs build
11+
12+
.PHONY: site-live
13+
site-live: $(VENV)
14+
$(VENV_BIN)/mkdocs serve
15+
16+
$(VENV): site-requirements.txt
17+
uv venv
18+
uv pip install -r site-requirements.txt

Diff for: ‎README.md

+8-120
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# zizmor
1+
# 🌈 zizmor
22

33
[![CI](https://github.com/woodruffw/zizmor/actions/workflows/ci.yml/badge.svg)](https://github.com/woodruffw/zizmor/actions/workflows/ci.yml)
44
[![Crates.io](https://img.shields.io/crates/v/zizmor)](https://crates.io/crates/zizmor)
@@ -8,129 +8,17 @@ A tool for finding security issues in GitHub Actions CI/CD setups.
88
> [!IMPORTANT]
99
> `zizmor` is currently in beta. You will encounter bugs; please file them!
1010
11-
Quick links:
11+
![](./docs/assets/zizmor-demo.gif)
1212

13-
* [Installation](#installation)
14-
* [Quick start guide](#quickstart)
15-
* [Usage](#usage)
16-
* [Online and offline use](#online-and-offline-use)
17-
* [Output formats](#output-formats)
18-
* [Audit documentation](./docs/audit/)
19-
* [Integration](#integration)
20-
* [Use in GitHub Actions](#use-in-github-actions)
21-
* [Technical details](#technical-details)
22-
* [Contributing](#contributing)
23-
* [The name?](#the-name)
13+
See [`zizmor`'s documentation](https://woodruffw.github.io/zizmor/)
14+
for [installation steps], as well as a [quickstart] and
15+
[detailed usage recipes].
2416

25-
Go right to the [Quickstart](#quickstart) or [Usage](#usage) to learn
26-
how to use `zizmor` locally or in your CI/CD.
17+
[installation steps]: https://woodruffw.github.io/zizmor/installation/
2718

28-
## Installation
19+
[quickstart]: https://woodruffw.github.io/zizmor/installation/
2920

30-
You can install `zizmor` from <https://crates.io> via `cargo`:
31-
32-
```bash
33-
cargo install zizmor
34-
```
35-
36-
or via [Homebrew](https://brew.sh/):
37-
38-
```bash
39-
brew install zizmor
40-
```
41-
42-
## Quickstart
43-
44-
You can run `zizmor` on any file(s) you have locally:
45-
46-
```bash
47-
# audit a specific workflow
48-
zizmor my-workflow.yml
49-
# discovers .github/workflows/*.yml automatically
50-
zizmor path/to/repo
51-
```
52-
53-
By default, `zizmor` will emit a Rust-style human-friendly findings, e.g.:
54-
55-
```console
56-
error[pull-request-target]: use of fundamentally insecure workflow trigger
57-
--> /home/william/devel/gha-hazmat/.github/workflows/pull-request-target.yml:20:1
58-
|
59-
20 | / on:
60-
21 | | # NOT OK: pull_request_target should almost never be used
61-
22 | | pull_request_target:
62-
| |______________________^ triggers include pull_request_target, which is almost always used insecurely
63-
|
64-
65-
1 findings (0 unknown, 0 informational, 0 low, 0 medium, 1 high)
66-
```
67-
68-
See the [Usage](#usage) for more examples, including examples of configuration.
69-
70-
## Usage
71-
72-
### Online and offline use
73-
74-
Some of `zizmor`'s audits require access to GitHub's API. `zizmor` will perform
75-
online audits by default *if* the user has a `GH_TOKEN` specified
76-
in their environment. If no `GH_TOKEN` is present, then `zizmor` will operate
77-
in offline mode by default.
78-
79-
Both of these can be made explicit through their respective command-line flags:
80-
81-
```bash
82-
# force offline, even if a GH_TOKEN is present
83-
zizmor --offline workflow.yml
84-
85-
# passing a token explicitly will forcefully enable online mode
86-
zizmor --gh-token ghp-... workflow.yml
87-
```
88-
89-
### Output formats
90-
91-
`zizmor` always produces output on `stdout`. If a terminal is detected,
92-
`zizmor` will default to a human-readable diagnostic output; if no terminal
93-
is detected, `zizmor` will emit JSON.
94-
95-
Output formats can be controlled explicitly via the `--format` option:
96-
97-
```bash
98-
# force diagnostic output, even if not a terminal
99-
zizmor --format plain
100-
101-
# emit zizmor's own JSON format
102-
zizmor --format json
103-
104-
# emit SARIF JSON instead of normal JSON
105-
zizmor --format sarif
106-
```
107-
108-
See [Integration](#integration) for suggestions on when to use each format.
109-
110-
## Integration
111-
112-
### Use in GitHub Actions
113-
114-
`zizmor` is trivial to use within GitHub Actions; you can run it just like
115-
you would locally.
116-
117-
`zizmor --format sarif` specifies [SARIF] as the output format, which GitHub's
118-
code scanning feature also supports.
119-
120-
See [GitHub's documentation] for advice on how to integrate `zizmor`'s results
121-
directly into a repository's scanning setup.
122-
123-
For a specific example, see `zizmor`'s own [repository workflow scan].
124-
GitHub's example of [running ESLint] as a security workflow provides additional
125-
relevant links.
126-
127-
[SARIF]: https://sarifweb.azurewebsites.net/
128-
129-
[GitHub's documentation]: https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github
130-
131-
[repository workflow scan]: https://github.com/woodruffw/zizmor/blob/main/.github/workflows/zizmor.yml
132-
133-
[running ESLint]: https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github#example-workflow-that-runs-the-eslint-analysis-tool
21+
[detailed usage recipes]: https://woodruffw.github.io/zizmor/installation/
13422

13523
## Technical details
13624

Diff for: ‎docs/DEVELOPMENT.md

-25
This file was deleted.

Diff for: ‎docs/assets/zizmor-demo.gif

73.5 KB
Loading

0 commit comments

Comments
 (0)