AI Security Setup | Contexa Docs

@EnableAISecurity 어노테이션

@EnableAISecurity는 레거시 시스템과의 심리스한 통합을 위해 제공되는 핵심 어노테이션입니다. Spring Boot의 주 설정 클래스(보통 @SpringBootApplication이 선언된 클래스)에 이 어노테이션을 선언하는 것만으로 Contexa의 전체 AI 보안 프레임워크가 활성화됩니다.

선언 예시

@SpringBootApplication
@EnableAISecurity(
    mode = SecurityMode.SANDBOX,
    authObjectLocation = AuthObjectLocation.AUTO
)
public class LegacyApplication {
    public static void main(String[] args) {
        SpringApplication.run(LegacyApplication.class, args);
    }
}

어노테이션 속성 상세

속성	타입	기본값	설명
`mode`	`SecurityMode`	`SecurityMode.SANDBOX`	AI 보안의 동작 모드를 결정합니다.
`authObjectLocation`	`AuthObjectLocation`	`AuthObjectLocation.AUTO`	레거시 인증 객체를 추출할 위치를 힌트로 지정합니다.
`authObjectAttribute`	`String`	`""`	세션 또는 요청 속성 기반으로 인증 핸드오프를 수행할 때 사용할 속성명입니다.
`authObjectType`	`Class<?>`	`Object.class`	반사적(Reflective) 추출을 수행할 인증 객체의 구체적인 타입 힌트입니다.

SecurityMode 동작 방식

Contexa는 점진적인 마이그레이션과 안전한 배포를 지원하기 위해 두 가지 보안 동작 모드를 지원합니다.

SANDBOX (샌드박스 모드): 레거시 통합의 기본값입니다. AI 기반 차단(BLOCK)이나 MFA 강제(CHALLENGE) 등의 집행 조치를 실제 클라이언트 요청에 직접 적용하는 대신, 감지 및 분석 결과를 감사 로그로만 남깁니다. 기존 서비스 영향도를 최소화하면서 AI 모델의 탐지 성능을 튜닝할 때 유용합니다.
FULL (전체 보호 모드): 완전한 AI Native Zero Trust 보안을 집행합니다. 이상 징후나 위협이 감지되면 실시간으로 차단 페이지로 리다이렉트하거나 강한 MFA 인증 챌린지를 적용합니다.

AiSecurityImportSelector와 동적 와이어링

Contexa는 컴파일 타임 의존성을 격리하면서 동적으로 자동 구성을 부트스트랩하기 위해 AiSecurityImportSelector를 활용합니다.

@EnableAISecurity 어노테이션 내부에 선언된 @Import(AiSecurityImportSelector.class)에 의해 Spring Container 기동 시 이 셀렉터가 호출됩니다. AiSecurityImportSelector는 다음과 같은 절차를 밟습니다:

어노테이션의 메타데이터로부터 속성값(mode, authObjectLocation 등)을 읽어들입니다.
읽어들인 설정값들을 아래 표와 같이 시스템 프로퍼티(System Properties)로 바인딩하여 런타임에 전파합니다.
최종적으로 contexa-autoconfigure 모듈의 핵심 진입점인 io.contexa.autoconfigure.ai.AiSecurityConfiguration 클래스명을 Spring IoC 컨테이너에 전달하여 동적 임포트를 완료합니다.

바인딩되는 시스템 프로퍼티

시스템 프로퍼티 키	상응 어노테이션 속성	설명
`contexa.ai.security.mode`	`mode`	시스템 전체의 AI 보안 집행 강도를 제어합니다.
`contexa.ai.security.auth-object.location`	`authObjectLocation`	인증 브릿지가 legacy 인증 스탬프를 추출하는 위치입니다.
`contexa.ai.security.auth-object.attribute`	`authObjectAttribute`	핸드오프에 사용되는 구체적인 속성명 키 정보입니다.
`contexa.ai.security.auth-object.type`	`authObjectType`	역직렬화 및 리플렉션 매핑에 활용되는 클래스 타입 정보입니다.

인증 객체 추출 위치 (AuthObjectLocation)

레거시 인증 아티팩트를 획득하기 위해 AuthObjectLocation을 통해 명시적으로 위치를 지정할 수 있습니다.

AUTO: 기본 설정이며, 요청 속성, 세션, 헤더 등을 자동으로 순차 스캔하여 객체를 식별합니다.
SESSION: HttpSession 영역에서 대상 속성명으로 바인딩된 인증 객체를 로드합니다.
REQUEST_ATTRIBUTE: HttpServletRequest의 attribute 맵 내에서 데이터를 식별합니다.
HEADER: HTTP 요청 헤더로부터 전달받은 토큰 정보에서 추출합니다.

AI Security 활성화 및 부트스트랩