operant-mcp

Instructions

Implementation Reference

• src/tools/recon.ts:446-490 (handler)

  The handler for "recon_s3_bucket" which tests an S3 bucket for public listability and existence of sensitive files using curl.

  server.tool(
    "recon_s3_bucket",
    "Test an S3 bucket for public access (listing, reading). Returns bucket_url, listable, listing_snippet, and readable_files. Read-only requests to S3.",
    {
      bucket_name: z
        .string()
        .describe("S3 bucket name to test, e.g. 'assets.example.com'"),
    },
    async ({ bucket_name }) => {
      requireTool("curl");
  
      const bucketUrl = `https://${bucket_name}.s3.amazonaws.com`;
  
      // Test bucket listing
      const listing = await runCmd("curl", ["-sk", "-m", "10", `${bucketUrl}/`]);
      const listable =
        listing.stdout.includes("<ListBucketResult") ||
        listing.stdout.includes("<Contents>");
  
      // Try common sensitive files
      const sensitiveFiles = [
        "key.txt", "credentials.txt", "config.json", ".env",
        "backup.sql", "database.sql", "id_rsa", "secret.txt",
      ];
      const readable: string[] = [];
      for (const f of sensitiveFiles) {
        const res = await runCmd("curl", [
          "-sk", "-o", "/dev/null", "-w", "%{http_code}",
          "-m", "5",
          `${bucketUrl}/${f}`,
        ]);
        const status = /^\d+$/.test(res.stdout) ? parseInt(res.stdout, 10) : 0;
        if (status === 200) {
          readable.push(f);
        }
      }
  
      const result = {
        bucket_url: bucketUrl,
        listable,
        listing_snippet: listable ? listing.stdout.slice(0, 2000) : "",
        readable_files: readable,
      };
  
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };

• src/tools/recon.ts:446-490 (handler)

  The implementation of the `recon_s3_bucket` tool, which performs public access checks on an S3 bucket using `curl`.

  server.tool(
    "recon_s3_bucket",
    "Test an S3 bucket for public access (listing, reading). Returns bucket_url, listable, listing_snippet, and readable_files. Read-only requests to S3.",
    {
      bucket_name: z
        .string()
        .describe("S3 bucket name to test, e.g. 'assets.example.com'"),
    },
    async ({ bucket_name }) => {
      requireTool("curl");
  
      const bucketUrl = `https://${bucket_name}.s3.amazonaws.com`;
  
      // Test bucket listing
      const listing = await runCmd("curl", ["-sk", "-m", "10", `${bucketUrl}/`]);
      const listable =
        listing.stdout.includes("<ListBucketResult") ||
        listing.stdout.includes("<Contents>");
  
      // Try common sensitive files
      const sensitiveFiles = [
        "key.txt", "credentials.txt", "config.json", ".env",
        "backup.sql", "database.sql", "id_rsa", "secret.txt",
      ];
      const readable: string[] = [];
      for (const f of sensitiveFiles) {
        const res = await runCmd("curl", [
          "-sk", "-o", "/dev/null", "-w", "%{http_code}",
          "-m", "5",
          `${bucketUrl}/${f}`,
        ]);
        const status = /^\d+$/.test(res.stdout) ? parseInt(res.stdout, 10) : 0;
        if (status === 200) {
          readable.push(f);
        }
      }
  
      const result = {
        bucket_url: bucketUrl,
        listable,
        listing_snippet: listable ? listing.stdout.slice(0, 2000) : "",
        readable_files: readable,
      };
  
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };