Skip to content

hxResearch

hxresearch/ is the internal research and expertise repository for the hxEASM project.

It is not application runtime code. It is the knowledge layer: a long-term home for project-maintained security research, custom detection content, advisories, writeups, proof-of-concepts, datasets, and proprietary expertise.

Purpose

The platform has several moving parts:

  • platform code
  • plugin wrappers
  • configuration
  • scan profiles
  • report generation
  • future AI agents
  • research knowledge

hxresearch/ keeps the research knowledge layer separate from backend and frontend application code. This lets proprietary detections, advisories, and research material evolve without turning application packages into a mixed code-and-research archive.

Use hxresearch/ for:

  • custom detection templates
  • proprietary security research
  • project-authored advisories
  • vulnerability writeups
  • proof-of-concept material
  • validation datasets
  • reference material
  • expert knowledge used by plugins or future agents

Current Runtime Integration

Worker containers mount hxresearch/ read-only at:

/opt/hxeasm/hxresearch

The nuclei_custom_templates plugin reads custom Nuclei templates from:

/opt/hxeasm/hxresearch/nuclei

Only templates under hxresearch/nuclei are used by that plugin. Research files elsewhere in hxresearch/ are not executed by the plugin.

nuclei_custom_templates is registered in the backend plugin registry, but it is not included in any built-in scan profile. To use it, add it to a custom profile in backend/configs/config.yaml and restart both API and worker.

Structure

Current required structure:

hxresearch/
├── README.md
└── nuclei/
    ├── README.md
    ├── cves/
    ├── exposures/
    ├── misconfigurations/
    ├── technologies/
    └── zero-days/

Planned long-term structure may also include:

hxresearch/
├── advisories/
├── writeups/
├── poc/
└── datasets/

nuclei/

Custom Nuclei templates maintained by the project.

Use this directory for internal or project-authored templates, including newly researched vulnerabilities, product-specific detections, and validation checks that are not part of the standard ProjectDiscovery template set.

advisories/

Planned location for security advisories authored by the project team.

writeups/

Planned location for research reports and technical analyses.

poc/

Planned location for proof-of-concept exploit code and validation material.

PoC content must be clearly labeled, scoped, and separated from production scanning code. Do not wire PoCs into automated scan paths unless a future task explicitly designs that integration with safety controls.

datasets/

Planned location for research datasets and collected reference material.

Custom Nuclei Template Plugin

nuclei_custom_templates runs the nuclei binary with only the templates from hxresearch/nuclei:

nuclei -jsonl -no-color -duc -c 10 -t /opt/hxeasm/hxresearch/nuclei -list <target-file>

It does not run the default ProjectDiscovery template set.

Behavior:

  • missing template path fails clearly
  • existing but empty template path returns a successful skip
  • missing matching targets returns a successful skip
  • findings are normalized as vulnerability entities, like the standard nuclei plugin
  • metadata records source = nuclei_custom_templates

Example custom profile:

scan_profiles:
  expert_assessment:
    name: Expert Assessment
    description: Run internal hxEASM custom detections
    plugins:
      - subfinder
      - dnsx
      - httpx
      - nuclei_custom_templates

If scan_profile_order is configured, add expert_assessment to that list too.

Safety Rules

  • hxresearch/ is mounted read-only inside worker containers.
  • Custom templates must respect approved scope.
  • Do not add destructive payloads to automated templates.
  • Do not commit secrets, tokens, private customer data, or uncontrolled exploit automation.
  • No arbitrary user-uploaded templates are supported by this integration.
  • Review templates before enabling them in a scan profile.

Ownership

Research content should have clear ownership metadata where practical:

  • author or maintainer
  • creation date
  • last reviewed date
  • affected product or technology
  • source references
  • confidence level
  • validation status

For detection content, include whether it is experimental, validated, deprecated, or production-ready.

Future Integrations

Future integrations may include:

  • nuclei_hybrid: run ProjectDiscovery templates plus hxresearch/nuclei
  • advisory engines that read hxresearch/advisories
  • future AI agents that use curated hxresearch context
  • report sections referencing internal advisories and detection provenance
  • plugin wrappers that consume datasets from hxresearch/datasets

These integrations are future/planned unless explicitly documented as implemented.