• Stars
    star
    227
  • Rank 175,861 (Top 4 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 2 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

build APKs from source code

melange

Build apk packages using declarative pipelines.

Commonly used to provide custom packages for container images built with apko. The majority of apks are built for use with either the Wolfi or Alpine Linux ecosystems.

Key features:

  • Pipeline-oriented builds. Every step of the build pipeline is defined and controlled by you, unlike traditional package managers which have distinct phases.
  • Multi-architecture by default. QEMU is used to emulate various architectures, avoiding the need for cross-compilation steps.

Why

Secure software factories are the evolution of DevOps, allowing a user to prove the provenance of all artifacts incorporated into a software appliance. By building and capturing software artifacts into packages, DevOps teams can manage their software artifacts as if they were any other component of an image.

This is especially useful when building software appliances in the form of OCI container images with apko.

Installation

You can install Melange from Homebrew:

brew install melange

You can also install Melange from source:

go install chainguard.dev/melange@latest

You can also use the Melange container image:

docker run cgr.dev/chainguard/melange version

To use the examples, you'll generally want to mount your current directory into the container and provide elevated privileges, e.g.:

docker run --privileged -v "$PWD":/work cgr.dev/chainguard/melange build examples/gnu-hello.yaml

Running outside of a container requires Docker, but should also work with other runtimes such as podman.

Alternatively, if you're on a Mac, you can use the melange instructions for Lima to run an Alpine Linux VM.

Quickstart

A melange build file looks like:

package:
  name: hello
  version: 2.12
  epoch: 0
  description: "the GNU hello world program"
  copyright:
    - paths:
      - "*"
      attestation: |
        Copyright 1992, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2005,
        2006, 2007, 2008, 2010, 2011, 2013, 2014, 2022 Free Software Foundation,
        Inc.
      license: GPL-3.0-or-later
  dependencies:
    runtime:

environment:
  contents:
    repositories:
      - https://dl-cdn.alpinelinux.org/alpine/edge/main
    packages:
      - alpine-baselayout-data
      - busybox
      - build-base
      - scanelf
      - ssl_client
      - ca-certificates-bundle

pipeline:
  - uses: fetch
    with:
      uri: https://ftp.gnu.org/gnu/hello/hello-${{package.version}}.tar.gz
      expected-sha256: cf04af86dc085268c5f4470fbae49b18afbc221b78096aab842d934a76bad0ab
  - uses: autoconf/configure
  - uses: autoconf/make
  - uses: autoconf/make-install
  - uses: strip

We can build this with:

melange build examples/gnu-hello.yaml

or, with Docker:

docker run --privileged --rm -v "${PWD}":/work \
  cgr.dev/chainguard/melange build examples/gnu-hello.yaml

This will create a packages folder, with an entry for each architecture supported by the package. If you only want to build for the current architecture, you can add --arch $(uname -m) to the build command. Inside the architecture directory you should find apk files for each package built in the pipeline.

If you want to sign your apks, create a signing key with the melange keygen command:

melange keygen
 generating keypair with a 4096 bit prime, please wait...
 wrote private key to melange.rsa
 wrote public key to melange.rsa.pub

And then pass the --signing-key argument to melange build.

Debugging melange Builds

To include debug-level information on melange builds, edit your melange.yaml file and include set -x in your pipeline. You can add this flag at any point of your pipeline commands to further debug a specific section of your build.

...
pipeline:
  - name: Build Minicli application
    runs: |
      set -x
      APP_HOME="${{targets.destdir}}/usr/share/hello-minicli"
...

Default Substitutions

Melange provides the following default substitutions which can be referenced in the build file pipeline:

Substitution Description
${{package.name}} Package name
${{package.version}} Package version
${{package.epoch}} Package epoch
${{targets.destdir}} Directory where targets will be stored
${{targets.subpkgdir}} Directory where subpackage targets will be stored

An example build file pipeline with substitutions:

pipeline:
  - name: 'Create tmp dir'
    runs: mkdir ${{targets.destdir}}/var/lib/${{package.name}}/tmp

Usage with apko

To use a melange built apk in apko, either upload it to a package repository or use a "local" repository. Using a local repository allows a melange build and apko build to run in the same directory (or GitHub repo) without using external storage. An example of this approach can be seen in the nginx-image-demo repo.

Coming soon: Keyless signatures

We are working to enable keyless signatures using Sigstore Fulcio, which can be used with traditional signed indices to remove the need to have sensitive key material inside the build environment.

More Repositories

1

apko

Build OCI images from APK packages directly without Dockerfile
Go
747
star
2

osquery-defense-kit

Production-ready detection & response queries for osquery
Makefile
412
star
3

bincapz

detect malicious program behaviors
YARA
401
star
4

ssc-reading-list

A reading list for software supply-chain security.
327
star
5

incert

Add CA certificates into containers
Go
121
star
6

edu

Educational Resources for Software Supply Chain Security
HTML
76
star
7

actions

A collection of reusable Github Actions workflows.
65
star
8

justtrustme

Go
50
star
9

bomshell

An SBOM query language and associated utilities
Go
49
star
10

digestabot

Github Action to automatically update digests for container images.
Dockerfile
43
star
11

vex

vexctl is a tool to attest VEX impact statements
Go
43
star
12

bom-shelter

A place to systematically store software bill of materials (SBOM) documents.
Python
42
star
13

darkfiles

Darkfiles finds orphaned files in container images and makes them to bad deeds
Go
39
star
14

osqtool

Automated testing, generation & manipulation of #osquery packs
Go
36
star
15

go-apk

native go library for installation and management of apk packages
Go
29
star
16

registry-redirect

Go
29
star
17

cosign-ecs-verify

Lambda function for verifying signed images in ECS
Go
24
star
18

rules_apko

Bazel rules for apko
Starlark
23
star
19

crow-registry

TypeScript
21
star
20

clank

Simple tool that allows you to detect imposter commits in GitHub Actions workflows.
Go
21
star
21

yam

A sweet little formatter for YAML
Go
20
star
22

hakn

A High-Availability distribution of Knative.
Go
20
star
23

policy-catalog

Go
19
star
24

hello-melange-apko

Demo app duplicated in 5 languages (Go/JavaScript/Python/Ruby/Rust) showing how to go from source code to container image using melange+apko
Rust
19
star
25

tlogistry

Transparenty Immutable Container Image Tags
Go
19
star
26

clog

Context aware slog
Go
17
star
27

maxcve

Go
17
star
28

terraform-provider-apko

Go
14
star
29

image-comparison

Comparison of Chainguard Images to others
HTML
14
star
30

terraform-provider-oci

Terraform provider to perform OCI image operations
Go
12
star
31

exitdir

Common packages.
Go
8
star
32

go-oidctest

Library for creating fake OIDC providers in tests
Go
8
star
33

nginx-image-demo

nginx image demo
8
star
34

terraform-provider-cosign

Terraform provider for Sigstore Cosign
Go
8
star
35

yoloc

YOLO-level verifier
Go
7
star
36

admission-sidecar

Generic webhook controller / proxy for ease of integration with Styra in particular.
Go
7
star
37

terraform-infra-common

A repository containing a collection of "glue" modules for encapsulating common Cloud Run patterns.
HCL
7
star
38

pull-secret-updater

Go
6
star
39

vulnerability-scanner-support

Resources to help vulnerability scanners
6
star
40

stigs

HTML
6
star
41

platform-examples

Example apps demonstrating Chainguard platform integrations
Go
6
star
42

go-grpc-kit

Utility methods for gRPC.
Go
6
star
43

kolide-google-matcher

Unearth host mismatches between Kolide & Google Workspace
Go
6
star
44

learning-labs-static

Base code for Learning Labs: "Build Secure and Minimal Images with Chainguard Static Images"
Go
6
star
45

tekton-demo

Tekton and Sigstore Demo
HCL
5
star
46

terraform-publisher-apko

An experimental module for publishing images with tf-apko
HCL
5
star
47

images-autodocs

This project is now retired 👋
PHP
5
star
48

cve-bliss

Use this repo to submit your final project for the Painless Vulnerability Management With Chainguard course.
Dockerfile
5
star
49

text4shell-policy

ClusterImagePolicy demo for cve-2022-42889 text4shell
Java
4
star
50

melange-php-demos

PHP demos for Melange + Apko
PHP
4
star
51

gobump

Go tool to declaratively bump dependencies.
Go
4
star
52

homebrew-tap

Chainguard Homebrew Tap
Ruby
3
star
53

source-integrity-demo

Shell
3
star
54

tekton-helm-charts

Helm charts for deploying Tekton Pipelines, Dashboard and Chains
Smarty
3
star
55

rumble

Data collection for base image CVEs etc.
Go
3
star
56

sigstore-custom-policies

Repo to contain files demo'd on the CNCF Webinar on the Sigstore Policy Controller
CUE
3
star
57

terraform-google-cron

Terraform module for deploying cron jobs that run on a defined schedule
HCL
3
star
58

go-workqueue

Go
3
star
59

fixfilter

Filter scanner results by applying data from the Wolfi secdb
Go
2
star
60

edu-images-demos

Sample education demos for Chainguard Images
Dockerfile
2
star
61

secureframe-issue-sync

Sync Secureframe tests to GitHub issues (unofficial)
Go
2
star
62

terraform-aws-chainguard-account-association

Terraform module to connect Chainguard Enforce to your AWS Account
HCL
2
star
63

deved-autodocs

DEPRECATED. Moved to chainguard-dev/images-autodocs
PHP
2
star
64

terraform-google-chainguard-account-association

Terraform module to connect Chainguard Enforce to your Google Cloud project
HCL
2
star
65

hello-wolfi-demo

Demo for the Hello Wolfi workshop
PHP
2
star
66

terraform-provider-imagetest

Go
2
star
67

.github

Default files to be used for any public repository under the chainguard-dev organization.
2
star
68

chainguard-weaveworks-gitops-demo

End to End Security & Operations with Chainguard & Weave GitOps
Makefile
2
star
69

terraform-cloudrun-dashboard

THIS HAS MOVED
HCL
2
star
70

openssl-fips-test

Test that OpenSSL is configured to be FIPS-compliant
C
1
star
71

ldso-cache

reading and writing of glibc /etc/ld.so.cache files
Go
1
star
72

terraform-google-prober

A terraform module and Go library for deploying probers to Google Cloud Run
HCL
1
star
73

acls-in-yaml

Collect ACLs from SaaS platforms for periodic user access reviews
Go
1
star
74

field-demos

Public repository of field demos and collaboration and other goodness - it's not pretty, but it's shared ❤️
Dockerfile
1
star
75

go-pkgconfig

Go package for wrangling pkg-config data
Go
1
star
76

go-demo

go demo app
Go
1
star
77

cg-images-python-migration

Sample Flask application migrated to Chainguard Images
Dockerfile
1
star
78

trusted-cert

Un-forked clone of Trusted Cert operator so we can test github actions workflows
Go
1
star