@pensar/apex 1.8.0 → 2.0.0-canary.241920ad

package/README.md

@@ -84,6 +84,26 @@ pensar targeted-pentest --target https://example.com --objective "Test authentic
 | `--threat-model <text\|@file>` | pentest                   | Threat model to guide testing                  |
 | `--objective <text>`           | targeted-pentest          | Testing objective (repeatable)                 |
 
+### Logging
+
+Apex routes diagnostic/operational logging through a centralized structured logger
+(`src/core/logger`). It writes one-line JSON to **stderr** when output is not a TTY — keeping
+it separate from the program's stdout and easy to ship to a log pipeline (e.g. CloudWatch) —
+and pretty, colorized output in an interactive terminal. User-facing CLI/TUI output stays on
+stdout.
+
+Set the level (most → least verbose: `debug` < `info` < `warn` < `error`, default `info`):
+
+```bash
+pensar pentest --target https://example.com --log-level debug   # or --verbose / --quiet
+PENSAR_LOG_LEVEL=debug pensar ...                                # via environment
+PENSAR_DEBUG=1 pensar ...                                        # back-compat alias for debug
+```
+
+Resolution order: CLI flag → `PENSAR_LOG_LEVEL` → `PENSAR_DEBUG` → default `info`.
+`PENSAR_LOG_FORMAT=json|pretty` forces the output format. When Apex runs as a managed agent,
+`PENSAR_LOG_LEVEL` is supplied by the host environment.
+
 ### W&B Weave Tracing
 
 Stream step-level agent traces to Weights & Biases Weave for analysis and fine-tuning:
@@ -97,6 +117,17 @@ pensar pentest --target https://example.com
 
 Traces include reasoning steps, tool calls, token usage, and state checkpoints. When credentials are not set, tracing is silently disabled.
 
+### OpenTelemetry (Observability)
+
+Apex emits OpenTelemetry spans for agent runs, LLM calls, and tool executions through `@opentelemetry/api`. Spans are no-ops unless your process registers an OpenTelemetry SDK as the global tracer provider; Apex ships no SDK.
+
+Register an SDK before importing Apex code:
+
+- **Sentry**: install `@sentry/node` ≥ 9.27 and add `Sentry.vercelAIIntegration()` to your `Sentry.init` integrations.
+- **Any OTel backend** (Honeycomb, Tempo, Datadog, etc.): register `@opentelemetry/sdk-node` with an OTLP exporter.
+
+Spans follow [OTel GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Only span shape (model, token counts, latency, tool names) is captured by default; set `AI_TRACE_RECORD_PAYLOADS=true` to also record prompts, tool I/O, and outputs.
+
 ## Kali Linux Container (Optional)
 
 For **best performance**, run Apex in the included Kali Linux container with preconfigured pentest tools:

package/build/agent-7866ka7b.js

@@ -0,0 +1,218 @@
+import {
+  OffensiveSecurityAgent
+} from "./cli-gtepvg8s.js";
+import {
+  detectOSAndEnhancePrompt
+} from "./cli-4dpc999m.js";
+import"./cli-c8131c4q.js";
+import {
+  init_dist,
+  stepCountIs
+} from "./cli-5h1kv0v4.js";
+import"./cli-78s9w64j.js";
+import {
+  exports_external1 as exports_external,
+  init_zod
+} from "./cli-e6rgwtpb.js";
+import"./cli-gpnb45ck.js";
+import"./cli-rtbry75t.js";
+import"./cli-23xtyah8.js";
+import"./cli-k1vsv3qh.js";
+import"./cli-8rxa073f.js";
+
+// src/core/agents/specialized/findingJudge/agent.ts
+init_dist();
+
+// src/core/agents/specialized/findingJudge/prompts.ts
+var MAX_POC_SCRIPT_CHARS = 12000;
+var MAX_OUTPUT_CHARS = 16000;
+var MAX_EVIDENCE_CHARS = 8000;
+var MAX_DESCRIPTION_CHARS = 4000;
+function truncate(value, limit) {
+  if (value.length <= limit)
+    return value;
+  return value.substring(0, limit) + `
+... [truncated]`;
+}
+var FINDING_JUDGE_SYSTEM_PROMPT = `You are a security finding validation specialist running as an agentic verifier inside an automated penetration testing pipeline.
+
+You are the last line of defense against false positives, hallucinated findings, fabricated evidence, and overstated impact. Your job is to independently verify whether a submitted proof-of-concept and its output support the claimed finding.
+
+## Operating Rules
+
+- Use tools before accepting a finding. At minimum, rerun or inspect the PoC with execute_command, compare behavior with http_request, read saved artifacts, or research the relevant technology with web_search/get_page.
+- Stay in scope. Only interact with the target endpoint/host and artifacts from this session.
+- Do not create, edit, delete, or document findings. You only validate and call the response tool.
+- Do not run destructive payloads or broaden exploitation. Verification should be enough to confirm or refute the claim.
+- Distinguish "the PoC exited 0" from "the vulnerability is proven." A successful exit code is only supporting evidence.
+- If your investigation completes and the evidence does not support the claim, reject it with actionable concerns.
+- If tools fail or the environment blocks verification, report the limitation honestly in your response. Infrastructure failure fallback is handled by the caller, not by you.
+- Cite concrete observations from tool output, HTTP responses, or web research in reasoning, concerns, and toolEvidence.
+
+## Evaluation Criteria
+
+### Materiality
+- A finding is a vulnerability only when the observed behavior is exploitable now in a way that creates a concrete security risk for the assessed target and threat model.
+- Do not reward theoretical "missing control" findings unless the PoC shows a realistic abuse path, affected security boundary, and material consequence.
+- Evaluate behavior in context: application purpose, deployment model, data sensitivity, exposed trust boundaries, and whether the observed behavior is intended for that environment. Expected, documented, demo, sandbox, or training behavior is usually expected-behavior or informational unless the claim demonstrates impact outside that intended use.
+- Reject CVSS 0.0 findings rather than downgrading them. A non-zero LOW severity can still be valid when the PoC demonstrates real exploitability and security risk.
+- If a PoC only proves that input is accepted, an error is returned, a public endpoint is reachable, or a control is absent, reject when it does not show an exploitable security risk.
+
+### Correctness
+- SQL injection: output should show inaccessible data, query errors, or behavioral differences indicating injection success.
+- XSS: output should show payload reflection/execution in a browser-executable context.
+- Command injection / RCE: output should show execution on the target system, not only local command execution.
+- SSRF: output should show responses from internal or otherwise protected services.
+- Path traversal: output should show file contents outside the intended path.
+- IDOR: output should show access to another user's/account's resource while authentication exists.
+- Authentication bypass: output should show protected access without valid credentials.
+- Email/HTML injection: ideally verify delivery and rendering. If only server acceptance is shown, confidence must stay below 0.7 and limitations must state rendering was not independently verified.
+- Missing rate limiting / anti-automation: fewer than 50 requests is insufficient. Evidence must state exact request count, timing/distribution, and observed statuses.
+
+### Common Low-Signal Patterns
+Reject these unless the submitted evidence demonstrates concrete harm:
+- Missing rate limiting on non-sensitive, low-value, intentionally public, or low-abuse-potential endpoints.
+- Verbose errors, stack traces, framework versions, or internal paths without secrets, protected data, or a working exploit chain.
+- Missing input validation that only permits nulls, empty strings, negative values, long text, type coercion, or malformed JSON with no security boundary crossed.
+- Missing authentication on public, non-sensitive, catalog, status, listener, metadata, demo, or intentionally unauthenticated endpoints.
+- Client-side validation bypasses where direct API calls produce no server-side security impact.
+- User enumeration, timing differences, weak pseudonymization, and email masking weaknesses without credible account takeover, sensitive data exposure, or targeting impact.
+- Unhandled type errors, method confusion, and 500 responses that only prove fragile error handling.
+
+### Hallucination and Hardcoding
+Reject or lower confidence when:
+- The script prints "evidence" with echo/print/console.log that was never received from the target.
+- The script constructs fake HTTP responses or error messages.
+- The success condition is hardcoded or independent of target response content.
+- The script always exits 0.
+- Evidence text does not match live responses or the claimed endpoint.
+
+### Severity and Classification
+- Accept as vulnerability only when real target interaction demonstrates unintended, exploitable behavior that creates security risk.
+- Classify as informational when the observation is real but not currently exploitable or not security-impacting.
+- Classify as expected-behavior when the behavior is clearly by design.
+- Reject when the PoC fabricates evidence, does not demonstrate the claim, or the demonstrated impact fundamentally mismatches the finding.
+
+## Response Requirements
+
+Call the response tool exactly once. Include:
+- valid: true only when the finding should be persisted as an exploitable vulnerability. Use valid: false for informational, expected-behavior, CVSS 0.0, non-exploitable, or merely best-practice observations.
+- findingType: vulnerability, informational, or expected-behavior.
+- confidence: calibrated 0.0 to 1.0. Below 0.7 requires concerns.
+- reasoning: concise explanation grounded in concrete observations.
+- concerns: actionable concerns; empty only for valid high-confidence results.
+- verificationSteps: actions you performed.
+- toolEvidence: concrete observations from provided artifacts or tool outputs.
+- reproducedPoc: whether you reran or independently reproduced the PoC.
+- webResearchUsed: whether web research materially informed the judgment.
+- limitations: remaining gaps.`;
+function buildFindingJudgePrompt(input) {
+  const { pocScript, pocType, pocOutput, claim } = input;
+  return `# Finding Validation Request
+
+## Target
+
+**Target:** ${input.target || "Unknown"}
+**Claimed Endpoint:** ${claim.endpoint}
+**POC Path:** ${input.pocPath || "Not provided"}
+
+## Claimed Vulnerability
+
+**Title:** ${claim.title}
+**Vulnerability Class:** ${claim.vulnerabilityClass || "Unknown"}
+
+### Description
+${truncate(claim.description, MAX_DESCRIPTION_CHARS)}
+
+### Claimed Impact
+${truncate(claim.impact, MAX_DESCRIPTION_CHARS)}
+
+### Evidence Provided by Agent
+\`\`\`
+${truncate(claim.evidence, MAX_EVIDENCE_CHARS)}
+\`\`\`
+
+## Previously Executed POC (${pocType})
+
+\`\`\`${pocType === "javascript" ? "js" : pocType === "python" ? "python" : "bash"}
+${truncate(pocScript, MAX_POC_SCRIPT_CHARS)}
+\`\`\`
+
+## Previous POC Execution Output
+
+**Exit Code:** ${pocOutput.exitCode}
+
+### stdout
+\`\`\`
+${truncate(pocOutput.stdout || "(empty)", MAX_OUTPUT_CHARS)}
+\`\`\`
+
+### stderr
+\`\`\`
+${truncate(pocOutput.stderr || "(empty)", MAX_OUTPUT_CHARS / 2)}
+\`\`\`
+
+## Task
+
+Independently validate whether the submitted POC and observed behavior support the claimed finding. Use the available minimal tools to rerun or inspect the POC, compare live target behavior, read saved artifacts, or research public documentation/CVEs as needed.
+
+Do not document or mutate anything. When done, call response with your structured judgment.`;
+}
+
+// src/core/agents/specialized/findingJudge/types.ts
+init_zod();
+var FINDING_TYPES = [
+  "vulnerability",
+  "informational",
+  "expected-behavior"
+];
+var FindingJudgeOutputSchema = exports_external.object({
+  valid: exports_external.boolean().describe("Whether the POC demonstrates a currently exploitable vulnerability that should be persisted"),
+  findingType: exports_external.enum(FINDING_TYPES).describe("Classification: 'vulnerability' for genuine security issues, 'informational' for low-risk observations worth noting, 'expected-behavior' for findings that describe intentional design decisions"),
+  confidence: exports_external.number().min(0).max(1).describe("Confidence in the judgment, a decimal between 0.0 (no confidence) and 1.0 (certain)"),
+  reasoning: exports_external.string().describe("Brief explanation of the key tool observations and analysis that led to this judgment"),
+  concerns: exports_external.array(exports_external.string()).describe("Specific concerns identified. Empty array only when the finding is a valid high-confidence vulnerability."),
+  verificationSteps: exports_external.array(exports_external.string()).describe("Concrete verification actions performed before deciding."),
+  toolEvidence: exports_external.array(exports_external.string()).describe("Specific observations from tool output or provided artifacts."),
+  reproducedPoc: exports_external.boolean().describe("Whether the judge reran or independently reproduced the POC."),
+  webResearchUsed: exports_external.boolean().describe("Whether web_search/get_page materially informed the judgment."),
+  limitations: exports_external.array(exports_external.string()).describe("Remaining verification gaps or environmental limitations.")
+});
+
+// src/core/agents/specialized/findingJudge/agent.ts
+var FINDING_JUDGE_ACTIVE_TOOLS = [
+  "execute_command",
+  "http_request",
+  "read_file",
+  "list_files",
+  "grep",
+  "web_search",
+  "get_page",
+  "response"
+];
+
+class FindingJudgeAgent extends OffensiveSecurityAgent {
+  constructor(opts) {
+    const target = opts.finding.target ?? opts.target ?? opts.session.targets[0];
+    super({
+      system: detectOSAndEnhancePrompt(FINDING_JUDGE_SYSTEM_PROMPT),
+      prompt: buildFindingJudgePrompt({ ...opts.finding, target }),
+      model: opts.model,
+      session: opts.session,
+      target,
+      authConfig: opts.authConfig,
+      abortSignal: opts.abortSignal,
+      eventBus: opts.eventBus,
+      sandbox: opts.sandbox,
+      enableThinking: opts.enableThinking,
+      openAIReasoningEffort: opts.openAIReasoningEffort,
+      subagentId: opts.subagentId ?? "finding-judge",
+      activeTools: [...FINDING_JUDGE_ACTIVE_TOOLS],
+      responseSchema: FindingJudgeOutputSchema,
+      stopWhen: stepCountIs(60)
+    });
+  }
+}
+export {
+  FindingJudgeAgent
+};

package/build/agent-aj7jpehp.js

@@ -0,0 +1,25 @@
+import {
+  TargetedPentestAgent,
+  buildPentestActiveTools,
+  buildPentestPrompt,
+  buildPentestSystemPrompt
+} from "./cli-0svsmc2c.js";
+import"./cli-9fsre5pt.js";
+import"./cli-zyk3xsth.js";
+import"./cli-gtepvg8s.js";
+import"./cli-4dpc999m.js";
+import"./cli-c8131c4q.js";
+import"./cli-5h1kv0v4.js";
+import"./cli-78s9w64j.js";
+import"./cli-e6rgwtpb.js";
+import"./cli-gpnb45ck.js";
+import"./cli-rtbry75t.js";
+import"./cli-23xtyah8.js";
+import"./cli-k1vsv3qh.js";
+import"./cli-8rxa073f.js";
+export {
+  buildPentestSystemPrompt,
+  buildPentestPrompt,
+  buildPentestActiveTools,
+  TargetedPentestAgent
+};

package/build/agent-mjyx1amj.js

@@ -0,0 +1,19 @@
+import {
+  CodeAgent
+} from "./cli-demg7sj2.js";
+import"./cli-9fsre5pt.js";
+import"./cli-zyk3xsth.js";
+import"./cli-gtepvg8s.js";
+import"./cli-4dpc999m.js";
+import"./cli-c8131c4q.js";
+import"./cli-5h1kv0v4.js";
+import"./cli-78s9w64j.js";
+import"./cli-e6rgwtpb.js";
+import"./cli-gpnb45ck.js";
+import"./cli-rtbry75t.js";
+import"./cli-23xtyah8.js";
+import"./cli-k1vsv3qh.js";
+import"./cli-8rxa073f.js";
+export {
+  CodeAgent
+};