Skip to content

docs: document logging, fix badges and issues link #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stokpop merged 2 commits into from
Nov 9, 2026
Merged

docs: document logging, fix badges and issues link #23

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ab3b831
docs: document logging, fix badges and issues link
stokpop Oct 21, 2026
cabb982
Merge remote-tracking branch 'upstream/main' into pr23-merge
stokpop Nov 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 20 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
# Java Buildpack Security Provider

| Job | Status
| --- | ------
| `unit-test-8` | [![unit-test-master](https://java-experience.ci.springapps.io/api/v1/teams/java-experience/pipelines/security-provider/jobs/unit-test-8/badge)](https://java-experience.ci.springapps.io/teams/java-experience/pipelines/security-provider/jobs/unit-test-8)
| `deploy` | [![deploy-master](https://java-experience.ci.springapps.io/api/v1/teams/java-experience/pipelines/security-provider/jobs/deploy/badge)](https://java-experience.ci.springapps.io/teams/java-experience/pipelines/security-provider/jobs/deploy)
[![CI](https://github.com/cloudfoundry/java-buildpack-security-provider/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cloudfoundry/java-buildpack-security-provider/actions/workflows/ci.yml)

The `java-buildpack-security-provider` is a utility that watches for changes to container identity and trust stores and dynamically updates the KeyManager and TrustManager of an application.

The [Java buildpack](https://github.com/cloudfoundry/java-buildpack/blob/main/docs/framework-container_security_provider.md) installs it in every Java application; its documentation covers what it adds and how to disable the KeyManager or TrustManager.

## Certificate rotation
The KeyManager is reloaded when the instance identity certificate (`CF_INSTANCE_CERT`) changes. The Diego executor [writes the new private key (`CF_INSTANCE_KEY`) before the new certificate](https://github.com/cloudfoundry/executor/blob/208a08c51850167d93e1040cfd8538fc1925c882/depot/containerstore/instance_identity_handler.go#L94-L102), so only the certificate file is watched. Since 1.22.0, each load logs the certificate serial, subject and when the certificate chain expires (earliest expiry in the chain, in UTC).

Expand Down Expand Up @@ -34,6 +33,22 @@ Alert on these errors and restart the affected instance to get a new key pair:
$ cf restart-app-instance APP_NAME INDEX
```

## Logging
The provider logs through `java.util.logging`, with loggers named after its classes in the `org.cloudfoundry.security` package. At the default `INFO` level it logs each certificate load. `FINE` adds details such as the file events seen by the watcher, which show the order in which the certificate and private key files were replaced:

```
FINE org.cloudfoundry.security.FileWatcher: Discarding unimportant file change: instance.key
INFO org.cloudfoundry.security.FileWatchingX509ExtendedKeyManager: Updated KeyManager for ...
```

In a Spring Boot application, set the level like any other logger, e.g. with the environment variable `LOGGING_LEVEL_ORG_CLOUDFOUNDRY_SECURITY=DEBUG`. Otherwise, point `java.util.logging` at a configuration file shipped with the application, e.g. with `JAVA_OPTS: -Djava.util.logging.config.file=<path>`; the file replaces the default configuration, so it needs a handler as well:

```properties
handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=FINE
org.cloudfoundry.security.level=FINE
```

## Development
The project depends on Java 8. To build from source, run the following:

Expand All @@ -49,6 +64,6 @@ See [docs/RELEASE.md](docs/RELEASE.md) for how to cut a release, how it reaches
## License
This project is released under version 2.0 of the [Apache License][l].

[e]: https://github.com/cloudfoundry/security-provider/issues
[e]: https://github.com/cloudfoundry/java-buildpack-security-provider/issues
[l]: https://www.apache.org/licenses/LICENSE-2.0
[u]: https://help.github.com/articles/using-pull-requests
Loading