kgretzky/evilginx2 · error

credentials: missing `username` section

Error message

credentials: missing `username` section

What it means

Thrown during phishlet validation when the `credentials` section exists but lacks a `username` sub-section. The username sub-section tells Evilginx which form input holds the victim's username (via its `key` field) so credentials can be captured on submit and replayed later. Without it the phishlet is considered incomplete and is rejected.

Source

Thrown at core/phishlet.go:387

				p.customParams = *customParams
			} else {
				for _, param := range *fp.Params {
					p.customParams[param.Name] = param.Default
				}
			}*/
	}

	if fp.ProxyHosts == nil {
		return fmt.Errorf("missing `proxy_hosts` section")
	}
	if fp.AuthTokens == nil {
		return fmt.Errorf("missing `auth_tokens` section")
	}
	if fp.Credentials == nil {
		return fmt.Errorf("missing `credentials` section")
	}
	if fp.Credentials.Username == nil {
		return fmt.Errorf("credentials: missing `username` section")
	}
	if fp.Credentials.Password == nil {
		return fmt.Errorf("credentials: missing `password` section")
	}
	if fp.LoginItem == nil {
		return fmt.Errorf("missing `login` section")
	}

	for _, ph := range *fp.ProxyHosts {
		if ph.PhishSub == nil {
			return fmt.Errorf("proxy_hosts: missing `phish_sub` field")
		}
		if ph.OrigSub == nil {
			return fmt.Errorf("proxy_hosts: missing `orig_sub` field")
		}
		if ph.Domain == nil {
			return fmt.Errorf("proxy_hosts: missing `domain` field")
		}

View on GitHub (pinned to 4c0988a1d9)

Solutions

1. Add a `username:` sub-section inside `credentials:`
2. Give it a `key:` matching the username input's name/id and an optional `search:` (e.g. `any`, `id`, `name`)
3. Reload the phishlet with `config phishlets/local <name>` after editing

Example fix

// before
credentials:
  password:
    key: password
    search: any
// after
credentials:
  username:
    key: username
    search: any
  password:
    key: password
    search: any

var fp struct {
	Credentials *struct {
		Username *struct{} `yaml:"username"`
	} `yaml:"credentials"`
}
yaml.Unmarshal(data, &fp)
if fp.Credentials == nil || fp.Credentials.Username == nil {
	return errors.New("phishlet credentials must include a `username:` sub-section")
}

func hasUsername(fp *PhishletConfig) bool {
	return fp != nil && fp.Credentials != nil && fp.Credentials.Username != nil
}

err := cfg.AddPhishlet("local", name)
if err != nil {
	if strings.Contains(err.Error(), "missing `username` section") {
		log.Fatalf("phishlet %s: add credentials.username with key/search fields", name)
	}
	return err
}

When it happens

Trigger: A phishlet YAML defines `credentials:` but only includes `password:` (or neither field), leaving fp.Credentials.Username nil when Validate() runs.

Common situations: Deleting the username block while editing captured inputs; a phishlet ported from another tool that only captures passwords; indentation error putting `username:` under `password:`.

Related errors

• credentials: missing `password` section
• missing `credentials` section
• missing `login` section
• proxy_hosts: missing `phish_sub` field
• proxy_hosts: missing `orig_sub` field

AI-assisted analysis of kgretzky/evilginx2@4c0988a1d9 (2026-09-05). Data as JSON: /api/errors/efb3fb9501fcaed7. Report an issue: GitHub.