Merge pull request #149 from kolyshkin/add-capability

Add capability package

.github/workflows/test.yml

@@ -17,7 +17,7 @@ jobs:
     - if: ${{ matrix.go-version == '1.18.x' }}
       run: |
         # This corresponds with the list in Makefile:1, but omits the "userns"
-        # module, which requires go1.21 as minimum.
+        # and "capability" modules, which require go1.21 as minimum.
         echo 'PACKAGES="mountinfo mount sequential signal symlink user"' >> $GITHUB_ENV
     - name: go mod tidy
       run: |

Makefile

@@ -1,4 +1,4 @@
-PACKAGES ?= mountinfo mount sequential signal symlink user userns # IMPORTANT: when updating this list, also update the conditional one in .github/workflows/test.yml
+PACKAGES ?= capability mountinfo mount sequential signal symlink user userns # IMPORTANT: when updating this list, also update the conditional one in .github/workflows/test.yml
 BINDIR ?= _build/bin
 CROSS ?= linux/arm linux/arm64 linux/ppc64le linux/s390x \
 	freebsd/amd64 openbsd/amd64 darwin/amd64 darwin/arm64 windows/amd64

capability/.codespellrc

@@ -0,0 +1,3 @@
+[codespell]
+skip = ./.git
+ignore-words-list = nd

capability/.golangci.yml

@@ -0,0 +1,6 @@
+linters:
+  enable:
+    - unconvert
+    - unparam
+    - gofumpt
+    - errorlint

capability/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+This file documents all notable changes made to this project since the initial fork
+from https://github.com/syndtr/gocapability/commit/42c35b4376354fd5.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2024-08-01
+
+This is a maintenance release, fixing a few minor issues.
+
+### Fixed
+ * Fixed future kernel compatibility, for real this time. [#11]
+ * Fixed [LastCap] to be a function. [#12]
+
+## [0.1.0] - 2024-07-31
+
+This is an initial release since the fork.
+
+### Breaking changes
+
+ * The `CAP_LAST_CAP` variable is removed; users need to modify the code to
+   use [LastCap] to get the value. [#6]
+ * The code now requires Go >= 1.21.
+
+### Added
+ * `go.mod` and `go.sum` files. [#2]
+ * New [LastCap] function. [#6]
+ * Basic CI using GHA infra. [#8], [#9]
+ * README and CHANGELOG. [#10]
+
+### Fixed
+ * Fixed ambient capabilities error handling in [Apply]. [#3]
+ * Fixed future kernel compatibility. [#1]
+ * Fixed various linter warnings. [#4], [#7]
+
+### Changed
+ * Go build tags changed from old-style (`+build`) to new Go 1.17+ style (`go:build`). [#2]
+
+### Removed
+ * Removed support for capabilities v1 and v2. [#1]
+ * Removed init function so programs that use this package start faster. [#6]
+ * Removed `CAP_LAST_CAP` (use [LastCap] instead). [#6]
+
+<!-- Doc links. TODO: change to new package name. -->
+[Apply]: https://pkg.go.dev/github.com/kolyshkin/capability#Capabilities.Apply
+[LastCap]: https://pkg.go.dev/github.com/kolyshkin/capability#LastCap
+
+<!-- Minor releases. -->
+[0.1.1]: https://github.com/kolyshkin/capability/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/kolyshkin/capability/compare/42c35b4376354fd5...v0.1.0
+
+<!-- PRs in 0.1.x releases. ->
+[#1]: https://github.com/kolyshkin/capability/pull/1
+[#2]: https://github.com/kolyshkin/capability/pull/2
+[#3]: https://github.com/kolyshkin/capability/pull/3
+[#4]: https://github.com/kolyshkin/capability/pull/4
+[#6]: https://github.com/kolyshkin/capability/pull/6
+[#7]: https://github.com/kolyshkin/capability/pull/7
+[#8]: https://github.com/kolyshkin/capability/pull/8
+[#9]: https://github.com/kolyshkin/capability/pull/9
+[#10]: https://github.com/kolyshkin/capability/pull/10
+[#11]: https://github.com/kolyshkin/capability/pull/11
+[#12]: https://github.com/kolyshkin/capability/pull/12

capability/LICENSE

@@ -0,0 +1,25 @@
+Copyright 2023 The Capability Authors.
+Copyright 2013 Suryandaru Triandana <[email protected]>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

capability/README.md

@@ -0,0 +1,11 @@
+This is a fork of (apparently no longer maintained)
+https://github.com/syndtr/gocapability package. It provides basic primitives to
+work with [Linux capabilities][capabilities(7)].
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/kolyshkin/capability.svg)](https://pkg.go.dev/github.com/kolyshkin/capability)
+
+## Alternatives
+
+ * https://pkg.go.dev/kernel.org/pub/linux/libs/security/libcap/cap
+
+[capabilities(7)]: https://man7.org/linux/man-pages/man7/capabilities.7.html

capability/capability.go

@@ -0,0 +1,134 @@
+// Copyright 2023 The Capability Authors.
+// Copyright 2013 Suryandaru Triandana <[email protected]>
+// All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package capability provides utilities for manipulating POSIX capabilities.
+package capability
+
+type Capabilities interface {
+	// Get check whether a capability present in the given
+	// capabilities set. The 'which' value should be one of EFFECTIVE,
+	// PERMITTED, INHERITABLE, BOUNDING or AMBIENT.
+	Get(which CapType, what Cap) bool
+
+	// Empty check whether all capability bits of the given capabilities
+	// set are zero. The 'which' value should be one of EFFECTIVE,
+	// PERMITTED, INHERITABLE, BOUNDING or AMBIENT.
+	Empty(which CapType) bool
+
+	// Full check whether all capability bits of the given capabilities
+	// set are one. The 'which' value should be one of EFFECTIVE,
+	// PERMITTED, INHERITABLE, BOUNDING or AMBIENT.
+	Full(which CapType) bool
+
+	// Set sets capabilities of the given capabilities sets. The
+	// 'which' value should be one or combination (OR'ed) of EFFECTIVE,
+	// PERMITTED, INHERITABLE, BOUNDING or AMBIENT.
+	Set(which CapType, caps ...Cap)
+
+	// Unset unsets capabilities of the given capabilities sets. The
+	// 'which' value should be one or combination (OR'ed) of EFFECTIVE,
+	// PERMITTED, INHERITABLE, BOUNDING or AMBIENT.
+	Unset(which CapType, caps ...Cap)
+
+	// Fill sets all bits of the given capabilities kind to one. The
+	// 'kind' value should be one or combination (OR'ed) of CAPS,
+	// BOUNDS or AMBS.
+	Fill(kind CapType)
+
+	// Clear sets all bits of the given capabilities kind to zero. The
+	// 'kind' value should be one or combination (OR'ed) of CAPS,
+	// BOUNDS or AMBS.
+	Clear(kind CapType)
+
+	// String return current capabilities state of the given capabilities
+	// set as string. The 'which' value should be one of EFFECTIVE,
+	// PERMITTED, INHERITABLE BOUNDING or AMBIENT
+	StringCap(which CapType) string
+
+	// String return current capabilities state as string.
+	String() string
+
+	// Load load actual capabilities value. This will overwrite all
+	// outstanding changes.
+	Load() error
+
+	// Apply apply the capabilities settings, so all changes will take
+	// effect.
+	Apply(kind CapType) error
+}
+
+// NewPid initializes a new Capabilities object for given pid when
+// it is nonzero, or for the current process if pid is 0.
+//
+// Deprecated: Replace with NewPid2.  For example, replace:
+//
+//	c, err := NewPid(0)
+//	if err != nil {
+//	  return err
+//	}
+//
+// with:
+//
+//	c, err := NewPid2(0)
+//	if err != nil {
+//	  return err
+//	}
+//	err = c.Load()
+//	if err != nil {
+//	  return err
+//	}
+func NewPid(pid int) (Capabilities, error) {
+	c, err := newPid(pid)
+	if err != nil {
+		return c, err
+	}
+	err = c.Load()
+	return c, err
+}
+
+// NewPid2 initializes a new Capabilities object for given pid when
+// it is nonzero, or for the current process if pid is 0.  This
+// does not load the process's current capabilities; to do that you
+// must call Load explicitly.
+func NewPid2(pid int) (Capabilities, error) {
+	return newPid(pid)
+}
+
+// NewFile initializes a new Capabilities object for given file path.
+//
+// Deprecated: Replace with NewFile2.  For example, replace:
+//
+//	c, err := NewFile(path)
+//	if err != nil {
+//	  return err
+//	}
+//
+// with:
+//
+//	c, err := NewFile2(path)
+//	if err != nil {
+//	  return err
+//	}
+//	err = c.Load()
+//	if err != nil {
+//	  return err
+//	}
+func NewFile(path string) (Capabilities, error) {
+	c, err := newFile(path)
+	if err != nil {
+		return c, err
+	}
+	err = c.Load()
+	return c, err
+}
+
+// NewFile2 creates a new initialized Capabilities object for given
+// file path.  This does not load the process's current capabilities;
+// to do that you must call Load explicitly.
+func NewFile2(path string) (Capabilities, error) {
+	return newFile(path)
+}