refactor: move internal packages to internal/ directory #9606

knqyf263 · 2025-10-07T13:13:06Z

Description

Reorganizes the codebase by moving packages not intended as public API from pkg/ to internal/
Makes it clearer which packages are part of the public API
Allows for more flexible internal refactoring without causing breaking changes
This was previously attempted in PRs refactor(app): use internal and separate configurations #291 and refactor(internal): export internal packages #887 six years ago

Background

Trivy is primarily distributed as a CLI tool, and using Trivy as a library is not recommended for community users. However, Aqua Security internally imports and uses Trivy as a library in our products. This refactoring helps us:

Clearly distinguish between the stable public API (in pkg/) that we maintain for backward compatibility
Move internal implementation details to internal/ where we can refactor freely without worrying about breaking changes
Make it explicit which packages are safe to import externally vs. which are internal-only

Why now?

This refactoring was previously attempted in PRs #291 and #887 six years ago but was abandoned because:

Trivy was evolving rapidly with frequent major changes
The development velocity was too high to maintain a stable internal/ boundary
The codebase was still in flux and not mature enough

Now, Trivy has matured:

The core architecture has stabilized
Major structural changes have become less frequent than before
We can now maintain a clearer separation between public and internal APIs

API Change Detection

We use go-apidiff to automatically detect API changes in PRs. With this refactoring:

go-apidiff automatically excludes internal/ packages from analysis
This means API change detection will now focus on truly important changes in pkg/
We'll get cleaner, more actionable API change reports without noise from internal refactoring
Breaking changes in public APIs will be more visible and easier to track

Changes

Moved packages from pkg/ to internal/
Updated all import paths
Updated .golangci.yaml and magefiles to reference correct paths

Checklist

I've read the guidelines for contributing to this repository.
I've followed the conventions in the PR title.
I've added tests that prove my fix is effective or that my feature works.
I've updated the documentation with the relevant information (if needed).
I've added usage information (if the PR introduces new options)
I've included a "before" and "after" example to the description (if the PR is a user interface change).

Move compliance, iac/providers, and iac/state to pkg/ as they are part of the public API. Keep clock, cloud, and policy in internal/ as they are internal implementation.

Export BuildComplianceReport and BuildSummary functions along with required types (Report, SummaryReport, ControlCheckResult, ControlCheckSummary) in pkg/compliance for external use.

- Replace mapfs.New() with fstest.MapFS in createDataFS() - Replace CycloneDXWriter with k8s.Write in cluster controller - Update compliance imports to use public types package - Update go.mod to use Trivy fork with public API changes TODO: Update go.mod to use main branch after aquasecurity/trivy#9606 merges

knqyf263 · 2025-10-07T19:10:25Z

internal/iac/adapters/terraform/google/adapt.go

This file appears as newly created on the GitHub UI because the proportion of import statements is high compared to the total number of lines, resulting in a low similarity to the original file, but it is correctly recognized as a rename in git.

knqyf263 · 2025-10-07T19:11:58Z

internal/iac/adapters/cloudformation/aws/adapt.go

knqyf263 · 2025-10-07T19:12:08Z

internal/iac/adapters/terraform/adapt.go

knqyf263 · 2025-10-07T19:12:14Z

internal/iac/adapters/terraform/aws/adapt.go

knqyf263 · 2025-10-07T19:13:04Z

internal/iac/adapters/terraform/azure/adapt.go

knqyf263 · 2025-10-07T19:13:11Z

internal/iac/adapters/terraform/cloudstack/adapt.go

knqyf263 · 2025-10-07T19:13:18Z

internal/iac/adapters/terraform/digitalocean/adapt.go

knqyf263 · 2025-10-07T19:13:38Z

internal/iac/adapters/terraform/nifcloud/nifcloud.go

knqyf263 · 2025-10-07T19:15:50Z

internal/iac/state/state.go

DmitriyLewen

LGTM.

I left comment about aws config.
Also it looks like we can move dependency and vulnerability packages.

DmitriyLewen · 2025-10-13T05:30:41Z

internal/cloud/aws/config/config.go

trivy-aws uses this package - https://github.com/aquasecurity/trivy-aws/blob/6e28982904fb3a988cfdfcd41a63ac0caac6e8d4/pkg/commands/run.go#L32

The default settings and trivial logic are used to load the AWS config, so I think it can be reimplemented in trivy-aws.

DmitriyLewen · 2025-10-13T09:05:02Z

internal/digest/digest.go

We use Digest in Package.
Can we move this package into internal?

nikpivkin · 2025-10-22T05:49:03Z

internal/iac/terraform/context/context.go

As we discussed earlier, let's leave pkg/iac/terraform public for now.

nikpivkin · 2025-10-22T06:04:45Z

internal/iac/scanners/terraform/scanner.go

Ditto, let's leave pkg/iac/scanners/terraform public for now.

knqyf263 force-pushed the refactor/move-packages-to-internal branch from 00f0f8f to 55e85bb Compare October 7, 2025 13:15

github-actions bot added the apidiff Indicates Go API changes relevant to library consumers (CLI compatibility may be unaffected) label Oct 7, 2025

This comment was marked as off-topic.

Sign in to view

aqua-bot requested a review from a team October 7, 2025 13:17

knqyf263 added 2 commits October 7, 2025 22:51

refactor: move internal packages from pkg/ to internal/ directory

ff8d12a

refactor: update import paths for moved packages

0330e3b

knqyf263 force-pushed the refactor/move-packages-to-internal branch from 55e85bb to 0330e3b Compare October 7, 2025 19:03

knqyf263 added 8 commits October 8, 2025 09:40

refactor: update magefiles paths for moved packages

1293801

refactor: move public API packages back to pkg/

aba6d6f

Move compliance, iac/providers, and iac/state to pkg/ as they are part of the public API. Keep clock, cloud, and policy in internal/ as they are internal implementation.

refactor: expose compliance API in pkg/compliance

d1320de

Export BuildComplianceReport and BuildSummary functions along with required types (Report, SummaryReport, ControlCheckResult, ControlCheckSummary) in pkg/compliance for external use.

refactor: move k8s back to pkg/ as public API

8447d01

refactor: move policy back to pkg/ as public API

4cddf9f

refactor: move iac/severity back to pkg/ as public API

e7b9571

refactor: move iac/scanners/kubernetes back to pkg/ as public API

1a0ddde

style: fix linter issues

869a6b0

knqyf263 mentioned this pull request Oct 8, 2025

refactor: use Trivy's public Go API instead of internal packages aquasecurity/trivy-operator#2777

Draft

knqyf263 commented Oct 8, 2025

View reviewed changes

knqyf263 marked this pull request as ready for review October 8, 2025 09:04

knqyf263 requested review from DmitriyLewen, afdesk, nikpivkin and simar7 as code owners October 8, 2025 09:04

DmitriyLewen reviewed Oct 13, 2025

View reviewed changes

internal/digest/digest.go

Copy link

Contributor

DmitriyLewen Oct 13, 2025 •

edited

Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We use Digest in Package.
Can we move this package into internal?

nikpivkin reviewed Oct 22, 2025

View reviewed changes

internal/iac/terraform/context/context.go

Copy link

Contributor

nikpivkin Oct 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As we discussed earlier, let's leave pkg/iac/terraform public for now.

nikpivkin reviewed Oct 22, 2025

View reviewed changes

internal/iac/scanners/terraform/scanner.go

Copy link

Contributor

nikpivkin Oct 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto, let's leave pkg/iac/scanners/terraform public for now.

refactor: move internal packages to internal/ directory #9606

Are you sure you want to change the base?

refactor: move internal packages to internal/ directory #9606

Conversation

knqyf263 commented Oct 7, 2025

Description

Background

Why now?

API Change Detection

Changes

Checklist

Uh oh!

This comment was marked as off-topic.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DmitriyLewen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DmitriyLewen Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DmitriyLewen Oct 13, 2025 •

edited

Loading