Merge pull request #2381 from adobe/security-and-contribution-clarifications

Security and contribution clarifications

Author: afranken

.github/CONTRIBUTING.md

@@ -16,4 +16,7 @@ All third-party contributions to this project must be accompanied by a signed co
 
 All submissions should come in the form of pull requests and need to be reviewed by project committers. Read [GitHub's pull request documentation](https://help.github.com/articles/about-pull-requests/) for more information on sending pull requests.
 
+All submissions must include unit tests for any new functionality or bug fixes. If you are adding a new feature, please include a test that demonstrates the feature.
+S3Mock uses Unit tests for function coverage, Spring Boot tests for component coverage, and integration tests against the Docker container artefact for end-to-end coverage. Please ensure that your code is covered by at least one of these test types.
+
 Lastly, please follow the [pull request template](PULL_REQUEST_TEMPLATE.md) when submitting a pull request!

README.md

@@ -16,8 +16,9 @@
     * [Usage of AWS S3 SDKs](#usage-of-aws-s3-sdks)
       * [Path-style vs Domain-style access](#path-style-vs-domain-style-access)
       * [Presigned URLs](#presigned-urls)
+      * [Self-signed SSL certificate](#self-signed-ssl-certificate)
     * [Usage of AWS CLI](#usage-of-aws-cli)
-    * [Usage of plain HTTP](#usage-of-plain-http)
+    * [Usage of plain HTTP / HTTPS with cURL](#usage-of-plain-http--https-with-curl)
     * [S3Mock configuration options](#s3mock-configuration-options)
     * [S3Mock Docker](#s3mock-docker)
       * [Start using the command-line](#start-using-the-command-line)
@@ -26,6 +27,7 @@
       * [Start using Docker compose](#start-using-docker-compose)
         * [Simple example](#simple-example)
         * [Expanded example](#expanded-example)
+      * [Start using self-signed SSL certificate](#start-using-self-signed-ssl-certificate)
     * [S3Mock Java](#s3mock-java)
       * [Start using the JUnit4 Rule](#start-using-the-junit4-rule)
       * [Start using the JUnit5 Extension](#start-using-the-junit5-extension)
@@ -39,6 +41,9 @@
   * [Build & Run](#build--run)
     * [Java](#java)
     * [Kotlin](#kotlin)
+  * [Governance model](#governance-model)
+  * [Vulnerability reports](#vulnerability-reports)
+  * [Security](#security)
   * [Contributing](#contributing)
   * [Licensing](#licensing)
 <!-- TOC -->
@@ -190,9 +195,18 @@ For instance, S3Mock does not verify the HTTP verb that the presigned uri was cr
 
 S3 SDKs can be used to create presigned URLs pointing to S3Mock if they're configured for path-style access. See the "Usage of..." section above for links to examples on how to use the SDK with presigned URLs.
 
+#### Self-signed SSL certificate
+
+S3Mock supports connections via HTTP and HTTPS. It includes a self-signed SSL certificate which is rejected by most HTTP clients by default.
+To use HTTPS, the self-signed certificate must be accepted by the client. 
+
+On command line, this can be done by setting the `--no-verify-ssl` option in the AWS CLI or by using the `--insecure` option in cURL, see below.
+
+Java and Kotlin SDKs can be configured to trust any SSL certificate, see links to `S3Client` creation above. 
+
 ### Usage of AWS CLI
 
-S3Mock can be used with the AWS CLI. Setting the `--endpoint-url` enables path-style access.
+S3Mock can be used with the AWS CLI. Setting the `--endpoint-url` enables path-style access, `--no-verify-ssl` is needed for HTTPS access.
 
 Examples:
 
@@ -211,9 +225,14 @@ Get object
 aws s3api get-object --bucket my-bucket --key my-file --endpoint-url=http://localhost:9090 my-file-output
 ```
 
-### Usage of plain HTTP
+Get object using HTTPS 
+```shell
+aws s3api get-object --bucket my-bucket --key my-file --no-verify-ssl --endpoint-url=https://localhost:9191 my-file-output
+```
 
-As long as the requests work with the S3 API, they will work with S3Mock as well.
+### Usage of plain HTTP / HTTPS with cURL
+
+As long as the requests work with the S3 API, they will work with S3Mock as well. Use `--insecure` to ignore SSL errors.
 
 Examples:
 
@@ -229,7 +248,12 @@ curl --request PUT --upload-file ./my-file http://localhost:9090/my-test-bucket/
 
 Get object
 ```shell
-curl --request GET http://localhost:9090/my-test-bucket/my-file
+curl --request GET http://localhost:9090/my-test-bucket/my-file -O
+```
+
+Get object using HTTPS
+```shell
+curl --insecure --request GET https://localhost:9191/my-test-bucket/my-file -O
 ```
 
 ### S3Mock configuration options
@@ -272,7 +296,7 @@ Example with configuration via environment variables:
 
 #### Start using the Fabric8 Docker-Maven-Plugin
 
-Our [integration tests](integration-tests) are using the Amazon S3 Client to verify the server functionality against the S3Mock. During the Maven build, the Docker image is started using the [docker-maven-plugin](https://dmp.fabric8.io/) and the corresponding ports are passed to the JUnit test through the `maven-failsafe-plugin`. See [`BucketV2IT`](integration-tests/src/test/kotlin/com/adobe/testing/s3mock/its/BucketV2IT.kt) as an example on how it's used in the code.
+Our [integration tests](integration-tests) are using the Amazon S3 Client to verify the server functionality against the S3Mock. During the Maven build, the Docker image is started using the [docker-maven-plugin](https://dmp.fabric8.io/) and the corresponding ports are passed to the JUnit test through the `maven-failsafe-plugin`. See [`BucketIT`](integration-tests/src/test/kotlin/com/adobe/testing/s3mock/its/BucketIT.kt) as an example on how it's used in the code.
 
 This way, one can easily switch between calling the S3Mock or the real S3 endpoint and this doesn't add any additional Java dependencies to the project.
 
@@ -385,6 +409,51 @@ $ ls locals3root/my-test-bucket
 bucketMetadata.json
 ```
 
+#### Start using self-signed SSL certificate
+
+S3Mock includes a self-signed SSL certificate:
+
+```shell
+$ curl -vvv --insecure --request GET https://localhost:9191/my-test-bucket/my-file -O
+[...]
+* Server certificate:
+*  subject: C=DE; ST=Hamburg; L=Hamburg; O=S3Mock; OU=S3Mock; CN=Adobe S3Mock
+*  start date: Jul 25 12:28:53 2022 GMT
+*  expire date: Nov 25 12:28:53 3021 GMT
+*  issuer: C=DE; ST=Hamburg; L=Hamburg; O=S3Mock; OU=S3Mock; CN=Adobe S3Mock
+*  SSL certificate verify result: self signed certificate (18), continuing anyway.
+[...]
+```
+
+To use a custom self-signed SSL certificate, derive your own Docker container from the S3Mock container:
+
+```dockerfile
+FROM adobe/s3mock:4.2.0
+
+ENV server.ssl.key-store=/opt/customcert.jks
+ENV server.ssl.key-store-password=password
+ENV server.ssl.key-alias=selfsigned
+
+RUN keytool -genkey -keyalg RSA -alias selfsigned \
+  -validity 360 \
+  -keystore /opt/customcert.jks \
+  -dname "cn=Test, ou=Test, o=Docker, l=NY, st=NY, c=US" \
+  -storepass password -keysize 2048 \
+  -ext "san=dns:localhost"
+```
+
+```shell
+$ curl -vvv --insecure --request GET https://localhost:9191/my-test-bucket/my-file -O
+[...]
+* Server certificate:
+*  subject: C=US; ST=NY; L=NY; O=Docker; OU=Test; CN=Test
+*  start date: May  9 14:33:40 2025 GMT
+*  expire date: May  4 14:33:40 2026 GMT
+*  issuer: C=US; ST=NY; L=NY; O=Docker; OU=Test; CN=Test
+*  SSL certificate verify result: self signed certificate (18), continuing anyway.
+[...]
+```
+
 ### S3Mock Java
 
 `S3Mock` Java libraries are released and published to the Sonatype Maven Repository and subsequently published to
@@ -575,9 +644,23 @@ This repo is built with Java 17, output is _currently_ bytecode compatible with
 ### Kotlin
 The [Integration Tests](integration-tests) are built in Kotlin.
 
+## Governance model
+
+The project owner and leads makes all final decisions. See the `developers` section in the [pom.xml](pom.xml) for a list of leads.
+
+## Vulnerability reports
+
+S3Mock uses GitHub actions to produce an SBOM and to check dependencies for vulnerabilities. All vulnerabilities are evaluated and fixed if possible.
+Vulnerabilities may also be reported through the GitHub issue tracker.
+
+## Security
+
+S3Mock is not intended to be used in production environments. It is a mock server that is meant to be used in development and testing environments only. It does not implement all security features of AWS S3, and should not be used as a replacement for AWS S3 in production.
+It is implemented using [Spring Boot](https://github.com/spring-projects/spring-boot), which is a Java framework that is designed to be secure by default.
+
 ## Contributing
 
-Contributions are welcomed! Read the [Contributing Guide](./.github/CONTRIBUTING.md) for more information.
+Contributions are welcome! Read the [Contributing Guide](./.github/CONTRIBUTING.md) for more information.
 
 ## Licensing
 

pom.xml

@@ -42,18 +42,6 @@
   </licenses>
 
   <developers>
-    <developer>
-      <name>Andreas Gudian</name>
-      <email>gudian@adobe.com</email>
-      <organization>Adobe</organization>
-      <organizationUrl>https://www.adobe.com</organizationUrl>
-    </developer>
-    <developer>
-      <name>Timo Eckhardt</name>
-      <email>eckhardt@adobe.com</email>
-      <organization>Adobe</organization>
-      <organizationUrl>https://www.adobe.com</organizationUrl>
-    </developer>
     <developer>
       <name>Arne Franken</name>
       <email>franken@adobe.com</email>

server/src/main/resources/application-debug.properties

@@ -1,5 +1,5 @@
 #
-#  Copyright 2017-2024 Adobe.
+#  Copyright 2017-2025 Adobe.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -15,8 +15,9 @@
 #
 
 # Enable debug logging for requests to better debug S3Mock
-#logging.level.root=debug
-logging.level.org.springframework.web=DEBUG
+logging.level.root=debug
+logging.level.org.springframework.web=debug
+logging.level.org.apache=debug
 spring.mvc.log-request-details=true
 
 # Enable JMX  when debugging

server/src/main/resources/application-trace.properties

@@ -1,5 +1,5 @@
 #
-#  Copyright 2017-2024 Adobe.
+#  Copyright 2017-2025 Adobe.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -16,4 +16,11 @@
 
 logging.level.root=trace
 logging.level.org.springframework.web=trace
+logging.level.org.apache=trace
 spring.mvc.log-request-details=true
+
+# Enable JMX  when debugging
+spring.jmx.enabled=true
+
+# Enable all actuator endpoints when debugging
+management.endpoints.web.exposure.include=*