Security-group block

Security groups can match users based on various criteria. The two most important default groups are:

• known-users: user is identified to services or has a reputation of 25 or more
• unknown-users: all other users

These other groups also exist by default:

• tls-users: all users who are using SSL/TLS
• webirc-users: all users using WEBIRC. (UnrealIRCd 5.2.0 and later)
• websocket-users: all users using Websockets. (UnrealIRCd 6.0.7 and later)

The server admin can change the criteria of all built-in security groups. They can also add new security groups, for Special users.

Where security groups are used

• In any mask { } item in the configuration file, like oper Oper { mask { security-group xyz; } ...
  • That is in: allow::mask, ban user::mask, require authentication::mask, oper::mask, except ban::mask, tld::mask, vhost::mask, link::incoming::mask, deny channel::mask, allow channel::mask, connthrottle::except, blacklist::except, set::restrict::commands::except, set::antimixedutf8::except and set::antirandom::except
• In the ~security-group extban, eg: MODE #chan +b ~security-group:unknown-users to block low reputation and unidentified users
• In the set::anti-flood block, where the groups known-users and unknown-users have different flood limits
• In the Connthrottle module to temporarily keep out unknown-users during an attack.
• Channel mode +f and +F take different actions if >75% of the flood is caused by unknown-users. When that is the case, they will temporarily ban ~security-group:unknown-users and still allow known-users in.
• In set name-of-security-group { } - through which you can override some set items per security group

Syntax

security-group <name> {
        /* Optionally set a priority for the security group */
        priority <number>;
        public <yes|no>;

        /* Match people based on ANY of these criteria (OR) */
        mask { <mask>; };
        ip { <ip>; };
        identified <yes|no>;
        webirc <yes|no>;
        websocket <yes|no>;
        tls <yes|no>;
        reputation-score <value>;
        connect-time <timevalue>;
        security-group { <list>; };
        account { <list>; };
        country { <list>; };
        asn { <list>; };
        realname { <list>; };
        certfp { <list>; };
        channel { <list>; };
        destination { <list>; };
        server-port { <list>; };
        rule "<crule>";

        /* Optionally EXCLUDE people based on this (even if they matched above) */
        exclude-mask { <mask>; };
        exclude-ip { <ip>; };
        exclude-identified <yes|no>;
        exclude-webirc <yes|no>;
        exclude-websocket <yes|no>;
        exclude-tls <yes|no>;
        exclude-reputation-score <value>;
        exclude-connect-time <timevalue>;
        exclude-security-group { <list>; };
        exclude-account { <list>; };
        exclude-country { <list>; };
        exclude-asn { <list>; };
        exclude-realname { <list>; };
        exclude-certfp { <list>; };
        exclude-channel { <list>; };
        exclude-destination { <list>; };
        exclude-server-port { <list>; };
        exclude-rule "<crule>";
}

The priority matters if you are going to use the security group in set::anti-flood::<securitygroup> or set block for a security group like set trusted-users { max-channels-per-user 20; }. The settings of the first security group that match will decide which settings apply. A lower number means higher priority! The group known-users has priority 100. If another group needs to be more important, you need to use a lower number, like 50, 40, 30, 20.

public decides if the security group should be shown to users in security group lists (currently only MODE #channel +b ~security-group:xxxxx). The default is no, so the names of custom security groups are not accidentally exposed to users. The build-in groups like known-users, unknown-users, websocket-users, etc. have public set to yes.

The items are as follows:

• mask: list of masks that would result in a match, like *.example.net
• ip: list of IP addresses that would result in a match, eg 127.* or using CIDR notation 127.0.0.0/8.
• identified: if set to yes, then if the user is identified to Services then it is considered a match.
• webirc: if set to yes, then if the user comes from a WEBIRC gateway then it is considered a match.
• websocket: if set to yes, then if the user uses WebSockets then it is considered a match. (Requires UnrealIRCd 6.0.7 or later)
• tls: if set to yes, then if the user is using a SSL/TLS connection then it is considered a match.
• reputation-score: if set to a value, like 10, then if the user has a reputation score of this value or higher, it is considered a match. You can also use <10 to say match on a score of below 10.
• connect-time: if set to a time value, like 300 (seconds) or 5m (5 minutes), then if the user has been connected for longer than this time, it is considered a match. You can also use a value like <5m to say less than 5 minutes.
• security-group: this is a match if any of the security groups in this list match.
• account: list of account name(s) that would result in a match, eg: account { TrustedAccount1; TrustedAccount2; }
• country: list of country codes that would result in a match, eg: country { NL; BE; UK; }
• asn: list of AS numbers, eg: asn { 64496; 64497; 64498; }
• realname: list of realnames (gecos) that would result in a match, eg: realname "*Bot*";
• certfp: list of certificate fingerprints (sha256) that would result in a match, eg: certfp "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef";
• channel: one or more channels the user can be in, optionally prefixed by symbols like ~&@%+ for matching status. Example: channel "@#main"; /* all ops in #main */. (Requires UnrealIRCd 6.1.2 or later)
• destination: the destination (client/channel) of the command, but only at places where this is supported. Currently this can be used in Restrict commands to bypass channel-message, for example. (Requires UnrealIRCd 6.1.7 or later)
• server-port: the server port the user is connected to, eg server-port 6697; or a list server-port { 6667; 7000; } (Requires UnrealIRCd 6.2.1 or later)
• rule: a Crule such as rule "!inchannel('#main') && (online_time()<180 || reputation()<50)";. (Requires UnrealIRCd 6.1.2 or later)
• Other Extended server bans (from 3rd party modules too) can expose more values

Matching rules:

• Any items set to no mean the check will be skipped (ignored).
• Any items set to yes that are true mean the result is a match. Only 1 item that is set to yes needs to match! (But.. see next..)
• If any of the exclude- items match then the final result is NOT a match, even if other things matched.

All the selection criteria of security groups are also available in mask { } items elsewhere in the configuration file (eg in the oper block, allow block, vhost block, etc.)

Example and changing the known-users group

The default security group known-users has the following settings:

security-group known-users {
        identified yes;
        webirc no;
        reputation-score 25;
}

If you have no security-group known-users { } in your configuration file then these are the defaults. If you want to change the settings, then add the block to your config and modify it.

The magic unknown-users security-group

The unknown-users security group is a special group matching users that are NOT matched by the known-users group. In other words: unknown-users is the same as !known-users (the exclamation mark prefix meaning 'NOT').

See also

• Reputation score: what is a reputation score, how is it calculated, and where else can it be used
• Extended bans: In particular the ~security-group extban that can be added in a channel to match a security group.
• Extended server bans: In particular ~security-group that can be used in GLINE/ELINE/etc to match a security group.