Container image security guidelines (EAP)

This page sets out the mandatory security requirements and strongly recommended recommendations for building container images used by your app. Following these guidelines ensures your app is hardened against infrastructure attacks, maintains strict tenant isolation, and meets the transparency standards required for Marketplace approval.

During the Marketplace approval process, we also review the images used by your app for compliance with these guidelines.

Summary

These guidelines complement the platform-level controls described in Forge Containers overview: Security. They map to controls in the NIST SP 800-190 Container Security Guide.

Requirements

This section lists mandatory requirements for images. If non-compliant images are pushed to the Forge Container registry and used by your app, vulnerabilities will be assigned in accordance with the Marketplace Security Bugfix policy.

Privilege level

Non-root execution. Running containers with elevated privileges is a primary vector for host-to-container escapes.

• Processes must run as a non-privileged user with UID 1000 and GID 1000. Root-owned processes will fail to deploy.

For more details, see Managing a service.

NIST SP 800-190 reference: 4.4.4 (App vulnerabilities).

Maintenance

Lifecycle rule. Stale container images pose a significant security risk because they contain outdated libraries and OS packages with known vulnerabilities (CVEs) that have been discovered since the image was last built.

• Images built more than 180 days ago are considered stale and will be blocked from production deployment.

NIST SP 800-190 reference: 4.2.2 (Stale images in registries).

Data privacy and tenant scoping

Strict tenant isolation. App developers must ensure that customer data is handled with care, and in accordance with the Forge shared responsibility model. Detailed best practices are available on our Data privacy guidelines for developers. In particular, apps utilising Forge containers should observe tenant isolation best practices:

• Scoped requests: Ensure that every request to an Atlassian-controlled service or endpoint is correctly scoped to an installation or invocation. While Forge handles much of this, any remote API calls that egress tenant-specific data must be disclosed in your Marketplace listing.
• Statelessness: Treat containers as ephemeral. Don't store durable customer data on the local disk; use Forge hosted storage (Forge KVS, Forge Custom Entities, Forge SQL, or the Object Store) or remotes instead.

For more details, see Tenant data isolation and Storage overview.

NIST SP 800-190 reference: 3.5.1 (Data privacy/integrity).

Data egress

Deny-by-default. The Forge Containers environment always operates under a deny-by-default network architecture.

• Egress proxy: All outbound traffic must be routed through the FORGE_EGRESS_PROXY_URL environment variable. Connections that bypass the proxy will be blocked.
• Inbound traffic: Your app must listen only on the port specified by the SERVER_PORT environment variable.

For more details, see API contract and Runtime egress permissions.

NIST SP 800-190 reference: 3.4.2 and 4.4.2 (Unbounded network access from containers).

Secret management

No hardcoded credentials. Hardcoded credentials are a major security risk.

API keys, tokens and other app secrets must not be stored staticaly in the image definition. Secrets and credentials can be injected as encrypted environment variables at build time or the Forge KVS secret store at runtime.

For more details, see Manage environment variables with the Forge CLI.

NIST SP 800-190 references: 3.1.4 (Embedded clear text secrets); 4.1.4 (Dynamic injection).

Recommendations

This section lists strongly recommended best practices. Any deviations from these recommendations may be flagged during app review.

Base image

Minimalist footprint. To reduce the attack surface, use base images that include only the libraries essential to your app's operation.

• Use distroless or minimal OS base images (for example, Alpine).
• Images that contain package managers (such as apt or yum) or full OS suites are discouraged.

NIST SP 800-190 reference: 3.1.1 (Image vulnerabilities).

Dependencies

Multi-stage builds. The final production image should be a clean runtime that does not contain the build tools used during development. Multi-stage builds let you use one image for building (with all the heavy compilers and tools) and a separate, clean image for production.

• Strip all compilers, build tools, and shells from the final runtime image. If a tool is not required for the app binary to run, remove it.
• Replace shell scripts with equivalent entrypoint binaries, or explicitly include a shell only when needed.
• Use Docker Debug to temporarily inspect or troubleshoot containers without altering the base image.

If your app requires a shell or a specific system utility to function, you must provide a documented use case during the app review process.

Approval criteria:

• Review: Atlassian evaluates the tool's necessity against the requested functionality.
• Decision: Use cases that can be achieved using native language libraries (for example, axios or fetch instead of curl) are rejected.
• Exemption: If the tool is a hard dependency for a core binary and no library alternative exists, it may be approved subject to additional static image scanning and hardening verification.

Best practice: Favour static binaries and library-based implementations to ensure your app passes the automated static image scan without requiring manual intervention.

NIST SP 800-190 reference: 2.3.1 (Image creation, testing, and accreditation).

Related information

• Forge Containers overview
• Manifest reference for containerised services
• API contract
• Managing a service
• Runtime egress permissions
• Storage overview
• NIST SP 800-190: Container Security Guide