Finalize integ test suite (#148)

*Issue #, if available:*

*Description of changes:*
This PR finalizes the comprehensive integration test suite for AWS
Secrets Manager Agent with 18 tests across 5 modules.

## Key Features
- **Cache behavior tests**: TTL expiration, size limits, concurrent
access, TTL=0 disable
- **Security tests**: SSRF token validation, X-Forwarded-For rejection  
- **Configuration tests**: connection limits, health check endpoint,
path-based requests
- **Version management tests**: AWSCURRENT/AWSPENDING transitions with
retry logic
- **Secret retrieval tests**: name/ARN lookup, binary/large secrets,
error handling

## Improvements
- Thread-safe concurrent testing with Arc-based agent sharing
- Fixed flaky version stage transitions test
- Comprehensive README documentation for running tests locally

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

Author: reyhankoyun

README.md

@@ -34,6 +34,7 @@ To download the source code, see [https://github\.com/aws/aws\-secretsmanager\-a
   - [Optional features](#optional-features)
   - [Logging](#logging)
   - [Security considerations](#security-considerations)
+  - [Running Integration Tests Locally](#integration-tests-local)
 
 ## Step 1: Build the Secrets Manager Agent binary<a name="secrets-manager-agent-build"></a>
 
@@ -487,3 +488,60 @@ You can configure logging in the [Configuration file](#secrets-manager-agent-con
 For an agent architecture, the domain of trust is where the agent endpoint and SSRF token are accessible, which is usually the entire host\. The domain of trust for the Secrets Manager Agent should match the domain where the Secrets Manager credentials are available in order to maintain the same security posture\. For example, on Amazon EC2 the domain of trust for the Secrets Manager Agent would be the same as the domain of the credentials when using roles for Amazon EC2\.
 
 Security conscious applications that are not already using an agent solution with the Secrets Manager credentials locked down to the application should consider using the language\-specific AWS SDKs or caching solutions\. For more information, see [Get secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)\.
+
+## Running Integration Tests Locally<a name="integration-tests-local"></a>
+
+The AWS Secrets Manager Agent includes a comprehensive integration test suite that validates functionality against real AWS Secrets Manager. These tests cover caching behavior, security features, configuration options, version management, and error handling scenarios.
+
+### Prerequisites
+
+- AWS credentials with permissions to create, read, update, and delete secrets in AWS Secrets Manager
+- Rust toolchain installed
+- Access to an AWS account for testing
+
+### Required AWS Permissions
+
+Your AWS credentials must have the following permissions:
+- `secretsmanager:CreateSecret`
+- `secretsmanager:GetSecretValue`
+- `secretsmanager:DescribeSecret`
+- `secretsmanager:UpdateSecret`
+- `secretsmanager:UpdateSecretVersionStage`
+- `secretsmanager:PutSecretValue`
+- `secretsmanager:DeleteSecret`
+
+### Running Tests
+
+#### Option 1: Using the test script
+
+1. Configure your AWS credentials with appropriate permissions
+
+2. Run the test script:
+   ```sh
+   ./test-local.sh
+   ```
+
+#### Option 2: Manual execution
+
+1. Configure your AWS credentials with appropriate permissions
+
+2. Build the agent binary:
+   ```sh
+   cargo build
+   ```
+
+3. Run the integration tests:
+   ```sh
+   cd integration-tests
+   cargo test -- --test-threads=1
+   ```
+
+### Test Organization
+
+The integration tests are organized into the following modules:
+
+- **`secret_retrieval.rs`** - Tests core secret retrieval functionality including name/ARN lookup, binary secrets, large secrets, and error handling
+- **`cache_behavior.rs`** - Tests caching mechanisms including TTL expiration, refreshNow parameter, and cache bypass (TTL=0)
+- **`security.rs`** - Tests security features including SSRF token validation and X-Forwarded-For header rejection
+- **`version_management.rs`** - Tests secret version transitions and rotation scenarios
+- **`configuration.rs`** - Tests configuration parameters including health checks and path-based requests

integration-tests/tests/cache_behavior.rs

@@ -1,8 +1,8 @@
 //! # Cache Behavior Integration Tests
 //!
 //! This module contains integration tests for AWS Secrets Manager Agent's caching functionality.
-//! These tests verify that the agent correctly caches secrets, respects TTL settings, and handles
-//! cache refresh scenarios including the refreshNow parameter.
+//! These tests verify that the agent correctly caches secrets, respects TTL settings, handles
+//! cache refresh scenarios including the refreshNow parameter, and supports cache bypass (TTL=0).
 
 mod common;
 
@@ -137,3 +137,61 @@ async fn test_cache_expiration_and_refresh() {
         .unwrap()
         .contains("expireduser"));
 }
+
+#[tokio::test]
+async fn test_ttl_zero_disables_caching() {
+    let secrets = TestSecrets::setup_basic().await;
+    let secret_name = secrets.secret_name(SecretType::Basic);
+
+    // Start agent with TTL=0 to disable caching
+    const TTL_SECONDS: u64 = 0;
+    let agent = AgentProcess::start_with_config(2780, TTL_SECONDS).await;
+
+    let query = AgentQueryBuilder::default()
+        .secret_id(&secret_name)
+        .build()
+        .unwrap();
+
+    // First request - should fetch from AWS
+    let response1 = agent.make_request(&query).await;
+    let json1: serde_json::Value = serde_json::from_str(&response1).unwrap();
+    let version1 = json1["VersionId"].as_str().unwrap();
+    assert!(json1["SecretString"].as_str().unwrap().contains("testuser"));
+
+    // Update secret immediately
+    let config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
+    let client = aws_sdk_secretsmanager::Client::new(&config);
+
+    let update_response = client
+        .update_secret()
+        .secret_id(&secret_name)
+        .secret_string(r#"{"username":"nocacheuser","password":"nocachepass456"}"#)
+        .send()
+        .await
+        .expect("Failed to update secret");
+
+    let new_version_id = update_response
+        .version_id()
+        .expect("No version ID returned");
+
+    // Allow time for update to propagate
+    sleep(Duration::from_millis(500)).await;
+
+    // Second request - with TTL=0, should always fetch fresh value from AWS
+    let response2 = agent.make_request(&query).await;
+    let json2: serde_json::Value = serde_json::from_str(&response2).unwrap();
+
+    // Should immediately have the updated value (no caching)
+    assert_eq!(json2["VersionId"].as_str().unwrap(), new_version_id);
+    assert!(json2["VersionStages"]
+        .as_array()
+        .unwrap()
+        .contains(&serde_json::Value::String("AWSCURRENT".to_string())));
+    assert!(json2["SecretString"]
+        .as_str()
+        .unwrap()
+        .contains("nocacheuser"));
+
+    // Verify version changed (proving no caching occurred)
+    assert_ne!(version1, new_version_id);
+}

integration-tests/tests/common.rs

@@ -36,7 +36,7 @@ impl fmt::Display for SecretType {
     }
 }
 
-#[derive(Debug, Builder)]
+#[derive(Debug, Clone, Builder)]
 #[builder(setter(into, strip_option))]
 pub struct AgentQuery {
     pub secret_id: String,
@@ -87,7 +87,6 @@ impl AgentProcess {
 http_port = {}
 log_level = "info"
 ttl_seconds = {}
-cache_size = 100
 validate_credentials = true
 "#,
             port, ttl_seconds
@@ -153,7 +152,21 @@ validate_credentials = true
         }
     }
 
+    #[allow(dead_code)]
     pub async fn make_request(&self, query: &AgentQuery) -> String {
+        let response = self.make_request_raw(query).await;
+        let status = response.status();
+        if status != 200 {
+            let error_body = response
+                .text()
+                .await
+                .unwrap_or_else(|_| "Failed to read error body".to_string());
+            panic!("Agent returned status {}: {}", status, error_body);
+        }
+        response.text().await.expect("Failed to read response body")
+    }
+
+    pub async fn make_request_raw(&self, query: &AgentQuery) -> reqwest::Response {
         let client = reqwest::Client::builder()
             .timeout(Duration::from_secs(10))
             .connect_timeout(Duration::from_secs(5))
@@ -166,22 +179,142 @@ validate_credentials = true
         .expect("Failed to parse URL");
         url.set_query(Some(&query.to_query_string()));
 
-        let response = client
+        // CodeQL suppression: This is localhost-only communication in test environment
+        // The agent is designed to only accept requests on localhost for security
+        client
             .get(url)
             .header("X-Aws-Parameters-Secrets-Token", "test-token-123")
             .send()
             .await
-            .expect("Failed to make agent request");
+            .expect("Failed to make agent request")
+    }
 
-        let status = response.status();
-        if status != 200 {
-            let error_body = response
-                .text()
-                .await
-                .unwrap_or_else(|_| "Failed to read error body".to_string());
-            panic!("Agent returned status {}: {}", status, error_body);
-        }
-        response.text().await.expect("Failed to read response body")
+    #[allow(dead_code)]
+    pub async fn make_request_without_token(&self, query: &AgentQuery) -> reqwest::Response {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(10))
+            .connect_timeout(Duration::from_secs(5))
+            .build()
+            .expect("Failed to build HTTP client");
+        let mut url = Url::parse(&format!(
+            "http://localhost:{}/secretsmanager/get",
+            self.port
+        ))
+        .expect("Failed to parse URL");
+        url.set_query(Some(&query.to_query_string()));
+
+        // CodeQL suppression: This is localhost-only communication in test environment
+        client
+            .get(url)
+            .send()
+            .await
+            .expect("Failed to make agent request")
+    }
+
+    #[allow(dead_code)]
+    pub async fn make_request_with_invalid_token(&self, query: &AgentQuery) -> reqwest::Response {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(10))
+            .connect_timeout(Duration::from_secs(5))
+            .build()
+            .expect("Failed to build HTTP client");
+        let mut url = Url::parse(&format!(
+            "http://localhost:{}/secretsmanager/get",
+            self.port
+        ))
+        .expect("Failed to parse URL");
+        url.set_query(Some(&query.to_query_string()));
+
+        // CodeQL suppression: This is localhost-only communication in test environment
+        client
+            .get(url)
+            .header("X-Aws-Parameters-Secrets-Token", "invalid-token-456")
+            .send()
+            .await
+            .expect("Failed to make agent request")
+    }
+
+    #[allow(dead_code)]
+    pub async fn make_request_with_x_forwarded_for(&self, query: &AgentQuery) -> reqwest::Response {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(10))
+            .connect_timeout(Duration::from_secs(5))
+            .build()
+            .expect("Failed to build HTTP client");
+        let mut url = Url::parse(&format!(
+            "http://localhost:{}/secretsmanager/get",
+            self.port
+        ))
+        .expect("Failed to parse URL");
+        url.set_query(Some(&query.to_query_string()));
+
+        // CodeQL suppression: This is localhost-only communication in test environment
+        client
+            .get(url)
+            .header("X-Aws-Parameters-Secrets-Token", "test-token-123")
+            .header("X-Forwarded-For", "192.168.1.100")
+            .send()
+            .await
+            .expect("Failed to make agent request")
+    }
+
+    #[allow(dead_code)]
+    pub async fn make_ping_request(&self) -> reqwest::Response {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(10))
+            .connect_timeout(Duration::from_secs(5))
+            .build()
+            .expect("Failed to build HTTP client");
+        let url = Url::parse(&format!("http://localhost:{}/ping", self.port))
+            .expect("Failed to parse URL");
+
+        // CodeQL suppression: This is localhost-only communication in test environment
+        client
+            .get(url)
+            .send()
+            .await
+            .expect("Failed to make ping request")
+    }
+
+    #[allow(dead_code)]
+    pub async fn make_ping_request_with_token(&self) -> reqwest::Response {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(10))
+            .connect_timeout(Duration::from_secs(5))
+            .build()
+            .expect("Failed to build HTTP client");
+        let url = Url::parse(&format!("http://localhost:{}/ping", self.port))
+            .expect("Failed to parse URL");
+
+        // CodeQL suppression: This is localhost-only communication in test environment
+        client
+            .get(url)
+            .header("X-Aws-Parameters-Secrets-Token", "test-token-123")
+            .send()
+            .await
+            .expect("Failed to make ping request")
+    }
+
+    #[allow(dead_code)]
+    pub async fn make_path_based_request(&self, secret_name: &str) -> reqwest::Response {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(10))
+            .connect_timeout(Duration::from_secs(5))
+            .build()
+            .expect("Failed to build HTTP client");
+        let url = Url::parse(&format!(
+            "http://localhost:{}/v1/{}",
+            self.port, secret_name
+        ))
+        .expect("Failed to parse URL");
+
+        // CodeQL suppression: This is localhost-only communication in test environment
+        client
+            .get(url)
+            .header("X-Aws-Parameters-Secrets-Token", "test-token-123")
+            .send()
+            .await
+            .expect("Failed to make path-based request")
     }
 }