container-source-policy 0.1.3 → 0.2.0

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 (2) hide show
  1. package/README.md +51 -21
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -1,43 +1,50 @@
1
1
  # container-source-policy
2
2
 
3
- Generate a Docker BuildKit **source policy** file (`docker buildx build --source-policy-file …`) by parsing Dockerfiles and pinning `FROM` images to immutable digests.
3
+ Generate a Docker BuildKit **source policy** file by parsing Dockerfiles and pinning `FROM` images to immutable digests.
4
4
 
5
5
  This helps make `docker buildx build` inputs reproducible without rewriting your Dockerfile.
6
6
 
7
+ See the [BuildKit documentation on build reproducibility](https://github.com/moby/buildkit/blob/master/docs/build-repro.md) for more details on source policies.
8
+
7
9
  ## Quick start
8
10
 
9
11
  ```bash
10
12
  container-source-policy pin --stdout Dockerfile > source-policy.json
11
- docker buildx build --source-policy-file source-policy.json -t my-image:dev .
13
+ EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=source-policy.json docker buildx build -t my-image:dev .
12
14
  ```
13
15
 
16
+ > **Note:** [`EXPERIMENTAL_BUILDKIT_SOURCE_POLICY`](https://docs.docker.com/build/building/variables/#experimental_buildkit_source_policy) is the environment variable used by Docker Buildx to specify a source policy file.
17
+
14
18
  ## Install
15
19
 
16
- ### Go (build from source)
20
+ Run directly without installing (recommended):
17
21
 
18
22
  ```bash
19
- go install github.com/tinovyatkin/container-source-policy@latest
20
- ```
23
+ # npm/bun
24
+ npx container-source-policy --help
25
+ bunx container-source-policy --help
21
26
 
22
- ### npm (prebuilt binary)
27
+ # Python
28
+ uvx container-source-policy --help
23
29
 
24
- ```bash
25
- npm i -g container-source-policy
26
- container-source-policy --help
30
+ # Ruby (requires RubyGems 3.3+)
31
+ gem exec container-source-policy --help
27
32
  ```
28
33
 
29
- ### PyPI (prebuilt binary)
34
+ Or install globally:
30
35
 
31
36
  ```bash
32
- pipx install container-source-policy
33
- container-source-policy --help
34
- ```
37
+ # Go (build from source)
38
+ go install github.com/tinovyatkin/container-source-policy@latest
35
39
 
36
- ### RubyGems (prebuilt binary)
40
+ # npm
41
+ npm i -g container-source-policy
37
42
 
38
- ```bash
43
+ # Python
44
+ pipx install container-source-policy
45
+
46
+ # Ruby
39
47
  gem install container-source-policy
40
- container-source-policy --help
41
48
  ```
42
49
 
43
50
  ## Usage
@@ -60,10 +67,16 @@ Write directly to a file:
60
67
  container-source-policy pin --output source-policy.json Dockerfile
61
68
  ```
62
69
 
63
- Then pass the policy to BuildKit / Buildx:
70
+ Then pass the policy to BuildKit / Buildx via the environment variable:
71
+
72
+ ```bash
73
+ EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=source-policy.json docker buildx build .
74
+ ```
75
+
76
+ Or use `buildctl` directly with the `--source-policy-file` flag:
64
77
 
65
78
  ```bash
66
- docker buildx build --source-policy-file source-policy.json .
79
+ buildctl build --frontend dockerfile.v0 --local dockerfile=. --local context=. --source-policy-file source-policy.json
67
80
  ```
68
81
 
69
82
  Shell completion scripts are available via Cobra:
@@ -74,6 +87,8 @@ container-source-policy completion zsh
74
87
 
75
88
  ## What gets pinned
76
89
 
90
+ ### Container images (`FROM`)
91
+
77
92
  - Looks at `FROM …` instructions across all provided Dockerfiles.
78
93
  - Skips:
79
94
  - `FROM scratch`
@@ -83,6 +98,20 @@ container-source-policy completion zsh
83
98
  - Resolves the image manifest digest from the registry and emits BuildKit `CONVERT` rules of the form:
84
99
  - `docker-image://<as-written-in-Dockerfile>` → `docker-image://<normalized>@sha256:…`
85
100
 
101
+ ### HTTP sources (`ADD`)
102
+
103
+ - Looks at `ADD <url> …` instructions with HTTP/HTTPS URLs.
104
+ - Skips:
105
+ - `ADD --checksum=… <url>` (already pinned)
106
+ - URLs containing unexpanded variables (`${VAR}`, `$VAR`)
107
+ - Fetches the checksum and emits `CONVERT` rules with `http.checksum` attribute.
108
+
109
+ **Optimized checksum fetching** — avoids downloading large files when possible:
110
+ - `raw.githubusercontent.com`: extracts SHA256 from ETag header
111
+ - GitHub releases: uses the API `digest` field (set `GITHUB_TOKEN` for higher rate limits)
112
+ - S3: uses `x-amz-checksum-sha256` response header (by sending `x-amz-checksum-mode: ENABLED`)
113
+ - Fallback: downloads and computes SHA256
114
+
86
115
  ## Development
87
116
 
88
117
  ```bash
@@ -100,11 +129,12 @@ UPDATE_SNAPS=true go test ./internal/integration/...
100
129
  ## Repository layout
101
130
 
102
131
  - `cmd/container-source-policy/cmd/`: Cobra CLI commands
103
- - `internal/dockerfile`: Dockerfile parsing (`FROM` extraction)
104
- - `internal/registry`: registry client (digest resolution)
132
+ - `internal/dockerfile`: Dockerfile parsing (`FROM` and `ADD` extraction)
133
+ - `internal/registry`: registry client (image digest resolution)
134
+ - `internal/http`: HTTP client (URL checksum fetching with optimizations)
105
135
  - `internal/policy`: BuildKit source policy types and JSON output
106
136
  - `internal/pin`: orchestration logic for `pin`
107
- - `internal/integration`: end-to-end tests with a mock registry and snapshots
137
+ - `internal/integration`: end-to-end tests with mock registry/HTTP server and snapshots
108
138
  - `packaging/`: wrappers for publishing prebuilt binaries to npm / PyPI / RubyGems
109
139
 
110
140
  ## Packaging
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "container-source-policy",
3
- "version": "0.1.3",
3
+ "version": "0.2.0",
4
4
  "description": "Generate Buildx container source policy file for a given Dockerfile",
5
5
  "repository": {
6
6
  "type": "git",
@@ -28,13 +28,13 @@
28
28
  },
29
29
  "homepage": "https://github.com/tinovyatkin/container-source-policy#readme",
30
30
  "optionalDependencies": {
31
- "container-source-policy-darwin-arm64": "0.1.3",
32
- "container-source-policy-darwin-x64": "0.1.3",
33
- "container-source-policy-linux-arm64": "0.1.3",
34
- "container-source-policy-linux-x64": "0.1.3",
35
- "container-source-policy-windows-arm64": "0.1.3",
36
- "container-source-policy-windows-x64": "0.1.3",
37
- "container-source-policy-freebsd-x64": "0.1.3"
31
+ "container-source-policy-darwin-arm64": "0.2.0",
32
+ "container-source-policy-darwin-x64": "0.2.0",
33
+ "container-source-policy-linux-arm64": "0.2.0",
34
+ "container-source-policy-linux-x64": "0.2.0",
35
+ "container-source-policy-windows-arm64": "0.2.0",
36
+ "container-source-policy-windows-x64": "0.2.0",
37
+ "container-source-policy-freebsd-x64": "0.2.0"
38
38
  },
39
39
  "scripts": {
40
40
  "postinstall": "node postinstall.js"